DJ.2. The Discovery Protocols

There are three closely related discovery protocols: one is used to discover one or more lookup services on a local area network (LAN), another is used to announce the presence of a lookup service on a local network, and the last is used to establish communications with a specific lookup service over a wide-area network (WAN).

DJ.2.1. 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.2. 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.2.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.

DJ.2.2.2. The Multicast Request Service

The multicast request service is not based on 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 data and object serialization facilities of the Java programming language to provide platform independence.

DJ.2.2.3. Request Packet Format

A multicast discovery request packet body must:

• Be 512 bytes in size or less, in order to fit into a single UDP datagram

• Encapsulate its parameters in a platform-independent manner

• Be straightforward to encode and decode

Accordingly, we define the packet format to be a contiguous series of bytes as would be produced by a java.io.DataOutputStream object writing into a java.io.ByteArrayOutputStream object. The contents of the packet, in order of appearance, are illustrated by the following fragment of pseudocode which generates the appropriate byte array:

int protoVersion;                       // protocol version 
int port;                               // port to contact 
java.lang.String[] groups;              // groups of interest 
net.jini.core.lookup.ServiceID[] heard; // known lookups 

java.io.ByteArrayOutputStream byteStr = 
    new java.io.ByteArrayOutputStream(); 
java.io.DataOutputStream objStr = 
    new java.io.DataOutputStream(byteStr); 

objStr.writeInt(protoVersion); 
objStr.writeInt(port); 
objStr.writeInt(heard.length); 
for (int i = 0; i < heard.length; i++) {
    heard[i].writeBytes(objStr); 
} 
objStr.writeInt(groups.length); 
for (int i = 0; i < groups.length; i++) {
    objStr.writeUTF(groups[i]); 
} 

byte[] packetBody = byteStr.toByteArray(); // the final result 

To elaborate on the roles of the variables above:

• The protoVersion variable contains an integer that indicates the version of the discovery protocol. This will permit interoperability between different protocol versions. For the current version of the discovery protocol, protoVersion must have the value 1.

• The port variable contains the TCP port respondents must connect to in order to continue the discovery process.

• The groups variable contains a set of strings (organized as an array) naming the groups the entity wishes to discover. This set may be empty, which indicates that all lookup services are being looked for.

• The heard variable contains a set of net.jini.core.lookup.ServiceID objects (organized as an array) that identify lookup services from which this entity has already heard and that do not need to respond to this request.

• The packetBody variable contains the marshalled discovery request in a form that is suitable for putting into a datagram packet or writing to an output stream.

The table below illustrates the contents of a multicast request packet body.

If the size of the packet body should exceed 512 bytes, the set of lookups from which an entity has heard must be left incomplete in the packet body, such that the size of the packet body will come to 512 bytes or less. How this is done is not specified. It is not permissible for implementations to simply truncate packets at 512 bytes.

Similarly, if the number of groups requested causes the size of a packet body to exceed 512 bytes, implementations must perform several separate multicasts, each with a disjoint subset of the full set of groups to be requested, until the entire set has been requested. Each request must contain the largest set of responses heard that will keep the size of the request below 512 bytes.

DJ.2.2.4. 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. The multicast response server to contact can be determined by using the source address of the request that has been received, along with the port number encapsulated in that request.

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 party that is looking for a lookup service proxy initiates unicast discovery.

DJ.2.3. Discovery Using the Multicast Request Protocol

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

DJ.2.3.1. Steps Taken by the Discovering Entity

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

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.

DJ.2.3.2. Steps Taken by the Multicast Request Server

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

DJ.2.3.3. Handling Responses from Multiple Djinns

What happens 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.3.1, 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.3 “The Join Protocol”.

DJ.2.4. 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.4.1. The Multicast Announcement Service

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.

Multicast announcement packets are constrained by the same requirements as multicast request packets. The fields in a multicast announcement packet body are as follows:

The fields have the following purposes:

• The protocol version field provides for possible future extensions to the protocol. For the current version of the multicast announcement protocol this field must contain the value 1. This field is written as if using the method java.io.DataOutput.writeInt.

• The host field contains the name of a host to be used by recipients to which they may perform unicast discovery. This field is written as if using the method java.io.DataOutput.writeUTF.

• The port field contains the TCP port of the above host at which to perform unicast discovery. This field is written as if using the method java.io.DataOutput.writeInt.

• The service ID field allows recipients to keep track of the services from which they have received announcements so that they will not need to unnecessarily perform unicast discovery. This field is written as if using the method net.jini.core.lookup.ServiceID.writeBytes.

• The count field indicates the number of groups of which the given lookup service is a member. This field is written as if using the method java.io.DataOutput.writeInt.

• This is followed by a sequence of strings equal in number to the count field, each of which is a group that the given lookup service is a member of. Each string is written as if using the method java.io.DataOutput.writeUTF.

If the size of the set of groups represented by a lookup service causes the size of a multicast announcement packet body to exceed 512 bytes, several separate packets must be multicast, each with a disjoint subset of the full set of groups, such that the full set of groups is represented by all packets.

DJ.2.4.2. The Protocol

The details of the multicast announcement protocol are simple. The entity that runs the lookup service takes the following steps:

An entity that wishes to listen for multicast announcements performs the following set of steps:

DJ.2.5. Unicast Discovery

While workgroup-level devices need to be able only to discover local djinns, a user might need to be able to access services in djinns that may be dispersed more widely (for example in offices in other cities or on other continents). To this end, the software at the user’s fingertips must be able to obtain a reference to the lookup service of a remote djinn. This is done using the unicast discovery protocol.

The unicast Jini 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.5.1. The Protocol

The unicast discovery protocol is a simple request-response protocol.

If an entity wishes to obtain a reference to a given djinn, the entity has a lookup locator object for that djinn and makes a TCP connection to the host and port specified by that lookup locator. It sends a unicast discovery request (see below), to which the remote host responds.

If a lookup service is responding to a multicast request, the request to which it is responding contains the address and port to respond to, and it makes a TCP connection to that address and port. The respondee sends a unicast discovery request, and the lookup service responds with a proxy.

The protocol diagram in Figure DJ.2.2 illustrates the flow when unicast discovery is initiated by a discovering entity.

The protocol diagram in Figure DJ.2.3 indicates the flow when a lookup service initiates unicast discovery in response to a multicast request.

DJ.2.5.2. Request Format

A discovery request consists of a stream of data as would be obtained by writing code similar to the following:

int protoVersion; // protocol version 

java.io.ByteArrayOutputStream byteStr = 
    new java.io.ByteArrayOutputStream(); 
java.io.DataOutputStream objStr = 
    new java.io.DataOutputStream(byteStr); 

objStr.writeInt(protoVersion); 

byte[] requestBody = byteStr.toByteArray(); // final result 

The protoVersion variable above must have a value of 1 for the current version of the unicast discovery protocol. The requestBody variable contains the discovery request as would be sent to the unicast discovery request service.

DJ.2.5.3. Response Format

The response to the above request consists of a stream of data as would be obtained by writing code similar to the following:

net.jini.core.lookup.ServiceRegistrar reg; 
    String[] groups; // groups registrar will respond with 

java.rmi.MarshalledObject obj = 
    new java.rmi.MarshalledObject(reg); 
java.io.ByteArrayOutputStream byteStr = 
    new java.io.ByteArrayOutputStream(); 
java.io.ObjectOutputStream objStr = new 
    java.io.ObjectOutputStream(byteStr); 

objStr.writeObject(obj); 
objStr.writeInt(groups.length); 
for (int i = 0; i < groups.length; i++) {
    objStr.writeUTF(groups[i]); 
} 

byte[] responseBody = byteStr.toByteArray(); // final result 

When the discovering entity receives this data stream, it can deserialize the MarshalledObject it has been sent and use the get method of that object to obtain a lookup service registrar for that djinn.