DJ - Jini^TM Discovery & Join Specification

DJ.1 Introduction

Entities that wish to start participating in a distributed system of Jini^TM technology-enabled services and/or devices, known as a djinn, must first obtain references to one or more Jini lookup services. The protocols that govern the acquisition of these references are known as the discovery 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 join protocol.

DJ.1.1 Terminology

A host is a single hardware device that may be connected to one or more networks. An individual host may house one or more Java^TM virtual machines¹ (JVM).

Throughout this document we make reference to a discovering entity, a joining entity, or simply an entity.

• A discovering entity 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.
• A joining entity 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.
• An entity 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.
• A group is a logical name by which a djinn is identified.

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 JVM that is hosted on a legacy system. Such distinctions will be made only when necessary.

DJ.1.2 Host Requirements

Hosts that wish to participate in a djinn must have the following properties:

• A functioning JVM, with access to all packages needed to run software written to the Jini specifications
• A properly configured network protocol stack

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.

DJ.1.2.1 Protocol Stack Requirements for IP Networks

Hosts that make use of IP for networking must have the following properties:

• 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 DHCP.
• Support for unicast TCP and multicast UDP. The former is used by subsystems using Jini technology such as Java Remote Method Invocation (Java RMI); both are used during discovery.
• Provision of some mechanism, such as a simple HTTP server, that facilitates the downloading of code (for example, for service proxies or Java Java RMI 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.

DJ.1.3 Protocol Overview

There are three related discovery protocols, each designed with different purposes:

• The multicast request protocol 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.
• The multicast announcement protocol 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.
• The unicast discovery protocol 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.

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.

DJ.1.4 Discovery in Brief

This section provides a brief overview of the operation of the discovery protocols. For a detailed description suitable for use by implementors, see Section DJ.2 "The Discovery Protocols".

DJ.1.4.1 Groups

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 URLs 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.

Although group names are arbitrary strings, it is recommended that DNS-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 public 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.

DJ.1.4.2 The Multicast Request Protocol

The multicast request protocol, shown in Figure DJ.1.1, proceeds as follows:

1. The entity that wishes to discover a djinn establishes a TCP-based server that accepts references to the lookup service. This server is an instance of the multicast response service.
2. Lookup services listen for multicast requests for references to lookup services for the groups they manage. These listening entities are instances of the multicast request service. This is not an Java RMI-based service; the protocol is described in Section DJ.2 "The Discovery Protocols".
3. 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.
4. 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 net.jini.core.lookup.ServiceRegistrar.

At this point, the discovering entity will have obtained one or more remote references to lookup services.

Figure DJ.1.1: The Multicast Request Protocol

DJ.1.4.3 The Multicast Announcement Protocol

The multicast announcement protocol follows these steps:

1. 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.
2. Lookup services prepare to take part in the unicast discovery protocol (see below) and send multicast announcements of their existence at regular intervals.

DJ.1.4.4 The Unicast Discovery Protocol

The unicast discovery protocol works as follows:

1. 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 net.jini.core.lookup.ServiceRegistrar interface over the connection.
2. 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 ServiceRegistrar object in response.

DJ.2 The Discovery Protocols

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 (LAN); 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.

DJ.2.1 Protocol Versions

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.

DJ.2.2 Discovery Formats

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 Section DJ.2.4.4 "Protocol Version 1 Request Packet Format".

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 discovery format ID which uniquely identifies a discovery format; this format ID is followed by discovery format data (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 protocol; 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.

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 net.jini.discovery.x500.SHA1withDSA format (specified in Section DJ.3.2) applies to the multicast request and announcement protocols, but not to the unicast discovery protocol.

DJ.2.2.1 Discovery Format Names

Each discovery format is uniquely identified by a discovery format name, 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 Java Language Specification, Second Edition. Examples of format names are net.jini.discovery.x500.SHA1withDSA, net.jini.discovery.ssl, and net.jini.discovery.kerberos (the formats associated with these names are specified in Sections DJ.3.2, DJ.3.4, and DJ.3.5, respectively).

DJ.2.2.2 Discovery Format IDs

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 0 is called the null discovery format ID, and is reserved. The SHA-1 hash function is specified in Federal Information Processing Standards Publication (FIPS PUB) 180-1. The UTF-8 encoding is specified in RFC 2279.

DJ.2.3 Protocol Roles

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.

DJ.2.4 The Multicast Request Protocol

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.

DJ.2.4.1 Protocol Participants

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.

On the requesting side live the following components:

• A multicast request client performs multicasts to discover nearby lookup services.
• A multicast response server listens for responses from those lookup services.

These components are paired; they do not occur separately. Any number of pairs of such components may coexist in a single JVM at any given time.

The lookup service houses the other two participants:

• A multicast request server listens for incoming multicast requests.
• A multicast response client responds to callers, passing each a proxy that allows it to communicate with its lookup service.

Although these components are paired, as on the client side, only a single pair will typically be associated with each lookup service.

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.

Figure DJ.2.1: Multicast Request Protocol Participants

DJ.2.4.2 The Multicast Request Service

The multicast request service is not based on Java Java RMI; 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 TCP/IP environment the network protocol used is multicast UDP. Request datagrams are encoded as a sequence of bytes, using the I/O facilities of the Java programming language to provide platform independence.

DJ.2.4.3 Request Packet Contents

Each multicast request packet carries the following values:

• The protocol version 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.
• The multicast response port value is an integer representing the TCP port number of the discovering entity's multicast response server.
• The requested groups 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.
• The heard lookup service IDs 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.

Protocol version 2 multicast request 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 request packets, this value is always 1.
• The multicast response host 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.

Protocol version 2 discovery formats may also specify additional values to be included in multicast request packets.

DJ.2.4.4 Protocol Version 1 Request Packet Format

The table below describes the contents of a multicast request protocol version 1 packet body.

Count	Data Type	Description
1	int	protocol version
1	int	multicast response port
1	int	service ID count
variable	net.jini.core.lookup.ServiceID	heard lookup service IDs
1	int	group count
variable	java.lang.String	requested 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. Values of type ServiceID are encoded in the format specified for the ServiceID.writeBytes 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.

DJ.2.4.5 Protocol Version 2 Request Packet Format

The table below describes the contents of a protocol version 2 multicast request 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 request packet must include at least the following values, described in Section DJ.2.4.3 "Request Packet Contents":

• Multicast response host
• Multicast response port
• Requested groups
• Heard lookup service IDs

DJ.2.4.6 Request Packet Size

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.

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.

DJ.2.4.7 The Multicast Response Service

Unlike the multicast request service, the multicast response service is a normal TCP-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.

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.

DJ.2.4.8 Discovery Using the Multicast Request Protocol

Described below is the discovery sequence for local area network (LAN)-based environments that use the multicast request protocol to discover one or more djinns.

The entity that wishes to discover a djinn takes the following steps:

1. It establishes a multicast request client, which will send packets to the well-known multicast network endpoint on which the multicast request service operates.
2. It establishes a TCP server socket that listens for incoming connections, over which the unicast discovery protocol is used. This server socket is the multicast response server socket.
3. It creates a set of net.jini.core.lookup.ServiceID objects. This set contains service IDs for lookup services from which it has already heard, and is initially empty.
4. 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.
5. For each response it receives via the multicast response service, it adds the service ID for that lookup service to the set it maintains.
6. 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.
7. 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.

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.

The lookup service that hosts an instance of the multicast request service takes the following steps:

1. 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.
2. 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.

   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.

3. 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:

1. It constructs a datagram socket object, set up to send to the well-known multicast endpoint on which the multicast announcement service operates.
2. It establishes the server side of the unicast discovery service.
3. 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:

1. 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.
2. It binds a datagram socket to the well-known multicast endpoint on which the multicast announcement service operates and listens for incoming multicast announcements.
3. 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.

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.

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:

1. 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.
2. The discovering entity transmits a hash of all of the data it has sent and received over the connection so far.
3. 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:

1. 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.
2. 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
3. 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:

1. It removes that group from the persistent set of groups to join.
2. 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.
3. 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. < p class="Body">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.²

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.

¹ As used in this document, the terms "Java virtual machine" or "JVM" mean a virtual machine for the Java platform.


² If you speak hexadecimal, you will notice that 4160 is the decimal representation of (CAFE - BABE).

License

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

http://www.apache.org/licenses/LICENSE-2.0