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 `net.jini.discovery.x500.SHA1withDSA` discovery format (specified in Section DJ.3.2) 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.
- 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.
###DJ.2.4.9 Handling Responses from Multiple Djinns
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:
If the entity provides a _finder_-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 Section DJ.2.4.8, and provide the ability to:
- Display the names and descriptions of the djinns it has found out about
- Allow the user to select zero or more djinns to join
- Continue to dynamically update its display, until the user has finished their selection
- Attempt to join all of those djinns the user selected
On the other hand, if the behavior of the entity is fully automated, it should follow the join protocol described in Section DJ.4 "The Join Protocol".
###DJ.2.5 The Multicast Announcement Protocol
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.
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.
###DJ.2.5.1 Announcement Packet Contents
The multicast announcement service uses multicast datagrams to communicate from a single client to an arbitrary number of servers. In a TCP/IP environment the underlying protocol used is multicast UDP. Each multicast announcement packet carries the following values:
- The_ protocol version_ 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.
- The_ unicast discovery host_ 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.
- The_ unicast discovery port_ value is an integer representing the TCP port number of the lookup service's unicast discovery server.
- The_ lookup service ID_ value is the service ID of the lookup service.
- The_ member groups_ value is a set of strings naming the discovery groups to which the lookup service belongs.
Protocol version 2 multicast announcement packets additionally carry at least the following values:
- The_ discovery format ID_ value is a 64-bit number indicating the discovery format in which the discovery format data of the packet has been encoded.
- The_ packet type_ value is an integer used to distinguish between multicast request and announcement packets. For announcement packets, this value is always 0.
- The_ sequence number_ 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 Section DJ.2.5.6, "Announcement Sequence Numbers".
Protocol version 2 discovery formats may also specify additional values to be included in multicast announcement packets.
###DJ.2.5.2 Protocol Version 1 Announcement Packet Format
The table below describes the contents of a protocol version 1 multicast announcement packet body.
|Count|Data Type|Description|
|1|`int`|protocol version|
|1|`java.lang.String`|unicast discovery host|
|1|`int`|unicast discovery port|
|1|`net.jini.core.lookup.ServiceID`|lookup service ID|
|1|`int`|group count|
|_variable_|`java.lang.String`|member groups|
Packet contents consist of a contiguous series of values in the order listed above from top to bottom. Values of type `int` and `String` are encoded in the formats specified for the `writeInt` and `writeUTF` methods of the `java.io.DataOutput` interface, respectively. The `ServiceID` value is encoded in the format specified for the `ServiceID.writeBytes` method. The number of group strings written must be equal to the group count value.
###DJ.2.5.3 Protocol Version 2 Announcement Packet Format
The table below describes the contents of a protocol version 2 multicast announcement packet body.
|Count|Data Type|Description|
|1|`int`|protocol version|
|1|`byte`|multicast packet type|
|1|`long`|discovery format ID|
_variable_|`byte`|discovery format data|
Packet contents consist of a contiguous series of values in the order listed above from top to bottom. Values of type `byte`, `int`, and `long` are encoded in the formats specified for the `writeByte`, `writeInt`, and `writeLong` methods of the `java.io.DataOutput` 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 Section DJ.2.5.1 "Announcement Packet Contents":
- Unicast discovery host
- Unicast discovery port
- Lookup service ID
- Member groups
- Sequence number
###DJ.2.5.4 Announcement Packet Size
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.
###DJ.2.5.5 Discovery Using the Multicast Announcement Protocol
Described below is the sequence of actions that are taken by a lookup service and discovering entity when participating in the multicast announcement protocol.
The lookup service takes the following steps:
- It constructs a datagram socket object, set up to send to the well-known multicast endpoint on which the multicast announcement service operates.
- It establishes the server side of the unicast discovery service.
- It multicasts announcement packets at intervals. The length of the interval is not mandated, but 120 seconds is recommended.
An entity that wishes to listen for multicast announcements performs the following set of steps:
- 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.
- It binds a datagram socket to the well-known multicast endpoint on which the multicast announcement service operates and listens for incoming multicast announcements.
- 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.
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 `net.jini.discovery.x500.SHA1withDSA` discovery format (specified in Section DJ.3.2) 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.
###DJ.2.5.6 Announcement Sequence Numbers
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 Section DJ.2.5.4 "Announcement Packet Size"), 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.
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.
##DJ.2.6 The Unicast Discovery Protocol
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.
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 TCP instead of multicast UDP.
###DJ.2.6.1 The Protocol
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.
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 `net.jini.core.discovery.LookupLocator` 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 `net.jini.core.lookup.ServiceRegistrar` interface--over the connection to the discovering entity.
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.
The protocol diagram in Figure DJ.2.2 illustrates the sequence of events when unicast discovery is initiated by a discovering entity.
![This image illustrates the actions described in DJ.2.5.1, when a discovering entity is the initiator.][3]
> Figure DJ.2.2: Unicast Discovery Initiated by a Discovering Entity
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.
![This image illustrates the actions described in DJ.2.5.1, when a lookup service is the initiator.][4]
> Figure DJ.2.3: Unicast Discovery Initiated by a Lookup Service
###DJ.2.6.2 Unicast Request Contents
Each unicast request carries the following value:
- The_ protocol version_ 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.
Protocol version 2 unicast requests additionally carry the following value:
- The_ proposed format IDs_ 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.
###DJ.2.6.3 Unicast Response Contents
Each unicast response carries the following values:
- The_ registrar proxy_ value is the proxy object for the lookup service, which implements the `net.jini.core.lookup.ServiceRegistrar` interface.
- The_ member groups_ value is a set of strings naming the discovery groups to which the lookup service belongs.
Protocol version 2 unicast responses additionally carry at least the following values:
- The_ protocol version_ 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.
- The_ selected format ID_ 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 _protocol version_ and _format ID_.
- The_ unicast discovery host_ 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.
- The_ unicast discovery port_ value is an integer representing the TCP port number of the lookup service's unicast discovery server.
Protocol version 2 discovery formats may also specify additional values to be included in unicast responses.
###DJ.2.6.4 Protocol Version 1 Request Format
The table below describes the contents of a protocol version 1 unicast request.
|Count|Data Type|Description|
|1|`int`|protocol version|
The `int` protocol version value is encoded in the format specified for the `writeInt` method of the `java.io.DataOutput` interface.
###DJ.2.6.5 Protocol Version 1 Response Format
The table below describes the contents of a protocol version 1 unicast response.
|Count|Data Type|Description|
|1|`java.rmi.MarshalledObject`|registrar proxy|
|1|`int`|group count|
|_variable_|`java.lang.String`|member groups|
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 `java.io.ObjectOutputStream`, and writing to it an instance of `java.rmi.MarshalledObject` containing the marshalled registrar proxy. Values of type `int` and `String` are encoded in the formats that would be generated by calling the `writeInt` and `writeUTF` methods of the same `ObjectOutputStream` instance used to write the `MarshalledObject` containing the registrar proxy. The number of group strings written must be equal to the group count value.
###DJ.2.6.6 Protocol Version 2 Request Format
The table below describes the contents of a protocol version 2 unicast request.
|Count|Data Type|Description|
|1|`int`|protocol version|
|1|unsigned `short`|proposed format ID count|
|_variable_|`long`|proposed format IDs|
Packet contents consist of a contiguous series of values in the order listed above from top to bottom. Values of type `int` and `long` are encoded in the formats specified for the `writeInt` and `writeLong` methods of the `java.io.DataOutput` interface, respectively. The unsigned `short` value is encoded as if it were cast to a signed `short` value, and then written in the format specified for the `writeShort` method of the `java.io.DataOutput` interface. The number of discovery format ID values written must be equal to the proposed format ID count value.
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.
###DJ.2.6.7 Protocol Version 2 Response Format
The table below describes the contents of a protocol version 2 unicast response.
|Count|Data Type|Description|
|1|`int`|protocol version|
|1|`long`|selected format ID|
|_variable_|`byte`|discovery format data|
Packet contents consist of a contiguous series of values in the order listed above from top to bottom. Values of type `byte`, `int`, and `long` are encoded in the formats specified for the `writeByte`, `writeInt`, and `writeLong` methods of the `java.io.DataOutput` 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 Section DJ.2.6.3, "Unicast Response Contents":
- Registrar proxy
- Member groups
- Unicast discovery host
- Unicast discovery port
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.
###DJ.2.6.8 Protocol Version 2 Discovery Format Negotiation
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.
##DJ.3 Standard Discovery Formats
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.
###DJ.3.1 The `net.jini.discovery.plaintext` Format
The `net.jini.discovery.plaintext` 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 `8507042184704347702`.
####DJ.3.1.1 Multicast Requests
The table below illustrates the layout for multicast request discovery format data specified by the `net.jini.discovery.plaintext` discovery format. The values to encode are described in Section DJ.2.4.5, "Protocol Version 2 Request Packet Format".
|Count|Data Type|Description|
|1|`java.lang.String`|multicast response host|
|1|unsigned `short`|multicast response port|
|1|unsigned `short`|group count|
|_variable_|`java.lang.String`|requested groups|
|1|unsigned `short`|service ID count|
|_variable_|`net.jini.core.lookup.ServiceID`|heard lookup service IDs|
The discovery format data consists of a contiguous series of values in the order listed above from top to bottom. Values of type `String` are encoded in the format specified for the `writeUTF` method of the `java.io.DataOutput` interface. Unsigned `short` values are encoded as if they were cast to signed `short` values, and then written in the format specified for the `writeShort` method of the `java.io.DataOutput` interface. Values of type `ServiceID` are encoded in the format specified for the `ServiceID.writeBytes` method. The number of group strings written must be equal to the group count value. The number of service IDs written must be equal to the service ID count value.
####DJ.3.1.2 Multicast Announcements
The table below illustrates the layout for multicast announcement discovery format data specified by the `net.jini.discovery.plaintext` discovery format. The values to encode are described in Section DJ.2.5.1, "Announcement Packet Contents".
|Count|Data Type|Description|
|1|`long`|sequence number|
|1|`java.lang.String`|unicast discovery host|
|1|unsigned `short`|unicast discovery port|
|1|unsigned `short`|group count|
|_variable_|`java.lang.String`|member groups|
|1|`net.jini.core.lookup.ServiceID`|lookup service ID|
The discovery format data consists of a contiguous series of values in the order listed above from top to bottom. Values of type `long` and `String` are encoded in the formats specified for the `writeLong` and `writeUTF` methods of the `java.io.DataOutput` interface, respectively. Unsigned `short` values are encoded as if they were cast to signed `short` values, and then written in the format specified for the `writeShort` method of the `java.io.DataOutput` interface. The `ServiceID` value is encoded in the format specified for the `ServiceID.writeBytes` method. The number of group strings written must be equal to the group count value.
####DJ.3.1.3 Unicast Responses
The table below illustrates the layout for unicast response discovery format data specified by the `net.jini.discovery.plaintext` discovery format. The values to encode are described in Section DJ.2.6.3, "Unicast Response Contents".
|Count|Data Type|Description|
|1|`java.lang.String`|unicast discovery host|
|1|unsigned `short`|unicast discovery port|
|1|unsigned `short`|group count|
|_variable_|`java.lang.String`|member groups|
|1|`net.jini.io.MarshalledInstance`|registrar proxy|
The discovery format data consists of a contiguous series of values in the order listed above from top to bottom. Values of type `String` are encoded in the format specified for the `writeUTF` method of the `java.io.DataOutput` interface. Unsigned `short` values are encoded as if they were cast to signed `short` values, and then written in the format specified for the `writeShort` method of the `java.io.DataOutput` interface. The registrar proxy is written in the same format that would be produced by constructing a `java.io.ObjectOutputStream`, and writing to it an instance of `net.jini.io.MarshalledInstance` containing the marshalled registrar proxy. The number of group strings written must be equal to the group count value.
###DJ.3.2 The `net.jini.discovery.x500.SHA1withDSA` Format
The `net.jini.discovery.x500.SHA1withDSA` format extends the multicast request and announcement encodings specified by the `net.jini.discovery.plaintext` format (see Sections DJ.3.1.1 and DJ.3.1.2), appending to each an authentication block containing the X.500 distinguished name of the sender coupled with the sender's DSA signature of all data in the packet up to, but not including, the authentication block. This discovery format thus supports integrity protection of multicast request and announcement packet contents, and sender authentication. It does not, however, support encryption of packet contents, nor does it apply to the unicast discovery protocol. The discovery format ID for this format is `-4239414871821148892`.
####DJ.3.2.1 Multicast Requests
The table below illustrates the layout for multicast request discovery format data specified by the `net.jini.discovery.x500.SHA1withDSA` discovery format.
|Count|Data Type|Description|
|1|`int`|plaintext data length|
|_variable_|`byte`|plaintext data|
|1|`java.lang.String`|sender X.500 distinguished name|
|_variable_|`byte`|sender DSA signature|
The discovery format data consists of a contiguous series of values in the order listed above from top to bottom. Values of type `int` and `String` are encoded in the formats specified for the `writeInt` and `writeUTF` methods of the `java.io.DataOutput` interface, respectively. The variable-length plaintext data referenced in the table above consists of the following values encoded according to the `net.jini.discovery.plaintext` discovery format for multicast requests, specified in Section DJ.3.1.1:
- Multicast response host
- Multicast response port
- Requested groups
- Heard lookup service IDs
The length of the `net.jini.discovery.plaintext` formatted data is indicated by the plaintext data length value immediately preceding it. The sender X.500 distinguished name is formatted in the string representation specified by _RFC 2253_. The sender DSA signature is encoded according to the specification for the `SHA1withDSA` signature algorithm in Appendix B of the _Java Cryptography Architecture API Specification & Reference_, which is based on _Federal Information Processing Standards Publication (FIPS PUB) 186_. The signature applies to all data from the start of the multicast request packet up to, but not including, the sender X.500 distinguished name.
####DJ.3.2.2 Multicast Announcements
The table below illustrates the layout for multicast announcement discovery format data specified by the `net.jini.discovery.x500.SHA1withDSA` discovery format.
|Count|Data Type|Description|
|1|`int`|plaintext data length|
|_variable_|`byte`|plaintext data|
|1|`java.lang.String`|sender X.500 distinguished name|
|_variable_|`byte`|sender DSA signature|
The discovery format data consists of a contiguous series of values in the order listed above from top to bottom. Values of type `int` and `String` are encoded in the formats specified for the `writeInt` and `writeUTF` methods of the `java.io.DataOutput` interface, respectively. The variable-length plaintext data referenced in the table above consists of the following values encoded according to the `net.jini.discovery.plaintext` discovery format for multicast announcements, specified in Section DJ.3.1.2:
- Sequence number
- Unicast discovery host
- Unicast discovery port
- Member groups
- Lookup service ID
The length of the `net.jini.discovery.plaintext` formatted data is indicated by the plaintext data length value immediately preceding it. The sender X.500 distinguished name is formatted in the string representation specified by _RFC 2253_. The sender DSA signature is encoded according to the specification for the `SHA1withDSA` signature algorithm in Appendix B of the _Java Cryptography Architecture API Specification & Reference_, which is based on _Federal Information Processing Standards Publication (FIPS PUB) 186_. The signature applies to all data from the start of the multicast announcement packet up to, but not including, the sender X.500 distinguished name.
###DJ.3.3 The `net.jini.discovery.x500.SHA1withRSA` Format
The `net.jini.discovery.x500.SHA1withRSA` format is nearly identical to the `net.jini.discovery.x500.SHA1withDSA` format specified in Section DJ.3.2, except that it uses RSA encryption for signing data, instead of DSA. Signatures are encoded according to the specification for the `SHA1withRSA` signature algorithm in Appendix B of the _Java Cryptography Architecture API Specification & Reference_. In all other respects, the two formats are the same. The discovery format ID for this format is -248696397102000882.
###DJ.3.4 The `net.jini.discovery.ssl` Format
The `net.jini.discovery.ssl` format specifies an encoding in which unicast response data is sent across a TLS/SSL (Transport Layer Security/Secure Socket Layer) connection. Encryption, authentication, and/or integrity protection may be provided by the underlying TLS/SSL connection, depending on the selected cipher suite. This discovery format does not apply to multicast requests or announcements. The discovery format ID for this format is `1816474798606646324`. TLS/SSL is specified in _RFC 2246_.
####DJ.3.4.1 Unicast Responses
In the `net.jini.discovery.ssl` format, transmission of unicast response data involves three steps:
- The discovering entity establishes a TLS/SSL connection between itself and the lookup service on top of the TCP connection over which it sent the unicast request.
- The discovering entity transmits a hash of all of the data it has sent and received over the connection so far.
- The lookup service also computes a hash of all of the data it has received and sent over the connection so far. If this hash value matches that sent by the discovering entity, then the lookup service sends the unicast response data encoded as described later in this section. If the hash does not match, the lookup service terminates the connection.
The hash sent by the discovering entity to the lookup service is computed as follows: first, a sequence of bytes is assembled consisting of the entire unicast request immediately followed by the portion of the unicast response that is not discovery format data--the initial protocol version followed by the selected format ID, as specified in Section DJ.2.6.7, "Protocol Version 2 Response Format". This sequence of bytes is then used as input to the SHA-1 hash function; the 160-bit result is sent in its entirety in big-endian order as the hash value. The SHA-1 hash function is specified in _Federal Information Processing Standards Publication (FIPS PUB) 180-1_.
The unicast response data sent by the lookup service, if the hashes match, consists of the following values encoded (on top of the secured TLS/SSL connection) according to the `net.jini.discovery.plaintext` discovery format for unicast responses, specified in Section DJ.3.1.3:
- Unicast discovery host
- Unicast discovery port
- Member groups
- Registrar proxy
###DJ.3.5 The `net.jini.discovery.kerberos` Format
The `net.jini.discovery.kerberos` format specifies an encoding in which unicast response data is sent across a connection secured using the Kerberos Version 5 GSS-API Mechanism, defined in _RFC 1964_. Kerberos provides authentication; encryption and integrity protection of the transmitted data may also be provided depending on the GSS-API context in use for the connection. This discovery format does not apply to multicast requests or announcements. The discovery format ID for this format is `5724038453852586603`. The Kerberos network authentication protocol is defined in _RFC 1510_; the GSS-API is defined in _RFC 2743_.
####DJ.3.5.1 Unicast Responses
Transmission of unicast response data in the `net.jini.discovery.kerberos` discovery format is similar to the `net.jini.discovery.ssl` format, except that the underlying connection is secured using the Kerberos Version 5 GSS-API Mechanism instead of TLS/SSL:
- The discovering entity establishes a GSS-API context for communicating with the lookup service, whose Kerberos principal it knows in advance. It then uses GSS-API tokens obtained from the established context to wrap all subsequent data sent to the lookup service (over the TCP connection on which the unicast request was originally transmitted). Also, all data subsequently received over the connection is unwrapped using the GSS-API.
- The discovering entity transmits a hash of all of the data it has sent and received over the connection so far. Multiple GSS-API tokens may be used to convey the hash. The hash is computed as specified in Section DJ.3.4.1
- The lookup service also computes a hash of all of the data it has received and sent over the connection so far. If this hash value matches that sent by the discovering entity, then the lookup service sends the unicast response data, encoded as specified in Section DJ.3.4.1, over the TCP connection to the discovering entity, using GSS-API tokens as described in step 1. Multiple GSS-API tokens may be used to convey the unicast response data.
##DJ.4 The Join Protocol
Having covered the discovery protocols, we continue on to describe the join protocol. This protocol makes use of the discovery protocols to provide a standard sequence of steps that services should perform when they are starting up and registering themselves with a lookup service.
###DJ.4.1 Persistent State
A service must maintain certain items of state across restarts and crashes. These items are as follows:
- Its service ID. A new service will not have been assigned a service ID, so this will be not be set when a service is started for the first time. After a service has been assigned a service ID, it must continue to use it across all lookup services.
- A set of attributes that describe the service's lookup service entry.
- A set of groups in which the service wishes to participate. For most services this set will initially contain a single entry: the empty string (which denotes the public group).
- A set of specific lookup services to register with. This set will usually be empty for new services.
Note that by "new service" here, we mean one that has never before been started, not one that is being started again or one that has been moved from one network to another.
###DJ.4.2 The Join Protocol
When a service initially starts up, it should pause a random amount of time (up to 15 seconds is a reasonable range). This will reduce the likelihood of a packet storm occurring if power is restored to a network segment that houses a large number of services.
####DJ.4.2.1 Initial Discovery and Registration
For each member of the set of specific lookup services to register with, the service attempts to perform unicast discovery of each one and to register with each one. If any fails to respond, the implementor may choose to either retry or give up, but the non-responding lookup service should not be automatically removed from the set if an implementation decides to give up.
#####Joining Groups
If the set of groups to join is not empty, the service performs multicast discovery and registers with each of the lookup services that either respond to requests or announce themselves as members of one or more of the groups the service should join.
#####Order of Discovery
The unicast and multicast discovery steps detailed above do not need to proceed in any strict sequence. The registering service must register the same sets of attributes with each lookup service, and must use a single service ID across all registrations.
####DJ.4.2.2 Lease Renewal and Handling of Communication Problems
Once a service has registered with a lookup service, it periodically renews the lease on its registration. A lease with a particular lookup service is cancelled only if the registering service is instructed to unregister itself.
If a service cannot communicate with a particular lookup service, the action it takes depends on its relation to that lookup service. If the lookup service is in the persistent set of specific lookup services to join, the service must attempt to reregister with that lookup service. If the lookup service was discovered using multicast discovery, it is safe for the registering service to forget about it and await a subsequent multicast announcement.
####DJ.4.2.3 Making Changes and Performing Updates
#####Attribute Modification
If a service is asked to change the set of attributes with which it registers itself, it saves the changed set in a persistent store, then performs the requested change at each lookup service with which it is registered.
#####Registering and Unregistering with Lookup Services
If a service is asked to register with a specific lookup service, it adds that lookup service to the persistent set of lookup services it should join, and then registers itself with that lookup service as detailed above.
If a service is asked to unregister from a specific lookup service and that service is in the persistent set of lookup services to join, it should be removed from that set. Whether or not this step needs to be taken, the service cancels the leases for all entries it maintains at that lookup service.
####DJ.4.2.4 Joining or Leaving a Group
If a service is asked to join a group, it adds the name of that group to the persistent set of groups to join and either starts or continues to perform multicast discovery using this augmented group.
If the service is requested to leave a group, the steps are a little more complex:
- It removes that group from the persistent set of groups to join.
- It removes all lookup services that match only that group in the set of groups it is interested in from the set it has discovered using multicast discovery, and unregisters from those lookup services.
- It either continues to perform multicast discovery with the reduced set of groups or, if the set has been reduced to empty, ceases multicast discovery.
##DJ.5 Network Issues
Now we will discuss various issues that pertain to the multicast network protocol used by the multicast discovery service. Much of the discussion centers on the Internet protocols, as the lookup discovery protocol is expected to be most heavily used on IP-based internets and intranets.
###DJ.5.1 Properties of the Underlying Transport
The network protocol that is used to communicate between a discovering entity and an instance of the discovery request service is assumed to be unreliable and connectionless, and to provide unordered delivery of packets.
This maps naturally onto both IP multicast and local-area IP broadcast, but should work equally well with connection-oriented reliable multicast protocols.
####DJ.5.1.1 Limiting Packet Sizes
Since we assume that the underlying transport does not necessarily deliver packets in order, we must address this fact. Although we could mandate that request packets contain sequence numbers, such that they could be reassembled in order by instances of the discovery request service, this seems excessive. Instead, we recommend that discovery requests not exceed 512 bytes in size, including headers for lower-level protocols. This squeaks in below the lowest required MTU size that is required to be supported by IP implementations.
###DJ.5.2 Bridging Calls to the Discovery Request Service
Whether or not calls to the discovery request service will need to be bridged across LAN or wide area network (WAN) segments will depend on the network protocol being used and the topology of the local network.
In an environment in which every LAN segment happens to host a Jini lookup service, bridging might not be necessary. This does not seem likely to be a typical scenario.
Where the underlying transport is multicast IP, intelligent bridges and routers must be able to forward packets appropriately. This simply requires that they support one of the multicast IP routing protocols; most router vendors already do so.
If the underlying transport were permitted to be local-area IP broadcast, some kind of intelligent broadcast relay would be required, similar to that described in the DHCP and BOOTP specifications. Since this would increase the complexity of the infrastructure needed to support the Jini discovery protocol, we mandate use of multicast IP instead of broadcast IP.
###DJ.5.3 Limiting the Scope of Multicasts
In an environment that makes use of IP multicast or a similar protocol, the joining entity should restrict the scope of the multicasts it makes by setting the time-to-live (TTL) field of outgoing packets appropriately. The value of the TTL field is not mandated, but we recommend that it be set to 15.
###DJ.5.4 Using Multicast IP as the Underlying Transport
If multicast IP is being used as the underlying transport, request packets are encapsulated using UDP (checksums must be enabled). A combination of a well-known multicast IP address and a well-known UDP port is used by instances of the discovery request service and joining entities.
###DJ.5.5 Address and Port Mappings for TCP and Multicast UDP
The port number for Jini lookup discovery requests is `4160`. This applies to both the multicast and unicast discovery protocols. For multicast discovery the IP address of the multicast group over which discovery requests should travel is `224.0.1.85`. Multicast announcements should use the address `224.0.1.84`.
##DJ.6 `LookupLocator` Class
The `LookupLocator` class provides a simple interface for performing unicast discovery, using version 1 of the unicast discovery protocol:
package net.jini.core.discovery;
import java.io.IOException;
import java.io.Serializable;
import java.net.MalformedURLException;
import net.jini.core.lookup.ServiceRegistrar;
public class LookupLocator implements Serializable {
protected String host;
protected int port;
public LookupLocator(String host, int port) {...}
public LookupLocator(String url) throws MalformedURLException {...}
public String getHost() {...}
public int getPort() {...}
public ServiceRegistrar getRegistrar() throws IOException, ClassNotFoundException {...}
public ServiceRegistrar getRegistrar(int timeout) throws IOException, ClassNotFoundException {...}
}
Each constructor takes parameters that allow the object to determine what IP address and TCP port number it should connect to.
The first constructor takes a host name and port number. It throws an `IllegalArgumentException` if the port number is not between 1 and 65535 (both included). It also throws an `IllegalArgumentException` if the `host` cannot be parsed according to any one of the following syntactical requirements:
- A `host` as required by a _server-based naming authority_ in section 3.2.2 of RFC 2396. This RFC defines the generic syntax for Uniform Resource Identifiers (URIs).
- A literal IPv6 address as defined by RFC 2732
- A literal IPv6 address as defined by RFC 3513
It throws a `NullPointerException` if the host name is `null`. On completion, the `host` and `port` fields are assigned the values of the input `host` and `port` parameters.
The second constructor takes a URL of scheme `"jini"` as defined in section DJ.6.1. It throws a `MalformedURLException` if the URL is invalid and a `NullPointerException` if the URL is `null`. On completion, the `host` and `port` fields are assigned the `host` and `port` components of the input URL. If no port is specified in the URL, the default value of `4160` specified in section DJ.6.1 is assumed.
Neither constructor performs the unicast discovery protocol, nor does either resolve the host name passed as argument.
The `getHost` method returns the `host` field, which is the name of the host with which this object attempts to perform unicast discovery. The `getPort` method returns the ` port` field, which is the TCP port at the host to which this object connects.
The `equals` method returns `true` if both instances have the same `host` and `port` fields. The case of the `host` is ignored. Alternative forms of the same IPv6 address for the `host` value are treated as being unequal.
The `hashCode` method returns a hash value calculated from the values of the `host` and `port` fields.
There are two forms of the `getRegistrar` method. Each performs unicast discovery and returns an instance of the proxy for the specified lookup service, or throws either an `IOException` or a `ClassNotFoundException` if a problem occurs during the discovery protocol. Each method performs unicast discovery every time it is called, connecting to a host and port determined by the values of the `host` and `port` fields respectively. If the host name for this object resolves to multiple IP addresses, it is assumed that a lookup service for the same djinn lives at each address.
The form of this method that takes a `timeout` parameter will throw a `java.io.InterruptedIOException` if it blocks for more than `timeout` milliseconds while waiting for a response. A value of 0 specifies an infinite timeout and a negative value causes this method to throw an `IllegalArgumentException`.
A similar timeout is implied for the no-arg form of this method. It invokes the one-arg form of the method, passing to it a timeout value. The timeout in milliseconds may be specified globally using the `net.jini.discovery.timeout` system property. A default equal to 60 seconds is assumed if the system property is not set, set to a negative value, or cannot be parsed as an `Integer`.
###DJ.6.1 Jini Technology URL Syntax
The syntax of the Jini technology URL is that of a _hierarchical_ URI with a _server-based naming authority_ (host and optional port). The URI syntax is defined in RFC 2396. The components of the URL must satisfy the following requirements:
- A _scheme_ of `"jini"` must be present.
- A _server-based naming authority_ must be present; _user-info_ must not be present. The _port_, if present, must be between 1 and 65535 (both included).
- A _path_ if present, must be `"/"`; path segments must not be present.
- There must not be any other components present.
If no port number is specified, the default is 4160.2
Four possible forms of the URL are:
- `jini://host`
- `jini://host/`
- `jini://host:port`
- `jini://host:port/`
###DJ.6.2 Serialized Form
|Class|`serialVersionUID`|Serialized Fields|
|`LookupLocator`|1448769379829432795L|`String host
int port`|
##DJ.7 History
|Version|Description|
|v1.0|Initial release of this specification.|
|v2.0|Add specification of version 2 of the multicast request, multicast announcement, and unicast discovery protocols. Add specification of standard discovery formats for version 2 of the discovery protocols. Change the 512-byte size limit for multicast packet contents from a requirement to a recommendation. Miscellaneous corrections.|
|v3.0|Correct specification for the computation of Discovery Format IDs. Clarify Jini Technology URL syntax. Clarify that null format ID unicast responses only need version number. Add format id for net.jini.discovery.x500.SHA1withRSA format. Miscellaneous edits.|
1As used in this document, the terms "Java virtual machine" or "JVM" mean a virtual machine for the Java platform.
2If you speak hexadecimal, you will notice that `4160` is the decimal representation of (`CAFE` - `BABE`).
[1]: images/discovery-speca.gif
[2]: images/discovery-spec2.gif
[3]: images/discovery-spec3.gif
[4]: images/discovery-spec4.gif