DU.6. Low-Level Discovery Protocol Utilities
The utilities presented in this section of the specification are useful when implementing higher-level utilities or other entities or components that will be involved in the Jini discovery process. These utilities encapsulate functionality that allow one to exercise more control when interacting with the Jini discovery protocols. Anyone wishing to provide their own implementation of the Jini lookup service or their own implementation of the discovery utilities presented previously in this specification, may find the utilities presented in this section useful when creating those alternate implementations.
DU.6.1. The Constants Class
DU.6.1.1. Overview
The Constants class provides easy access to defined constants that may be useful when participating in the discovery process.
DU.6.1.2. Other Types
The types defined in the specification of the Constants class are in the net.jini.discovery package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
java.net.InetAddress java.net.UnknownHostException
DU.6.1.3. The Class Definition
The public constants defined by the Constants class are as follows:
package net.jini.discovery;
public class Constants {
public static final short discoveryPort = 4160;
public static final InetAddress getRequestAddress()
throws UnknownHostException {...}
public static final InetAddress getAnnouncementAddress()
throws UnknownHostException {...}
} DU.6.1.4. The Semantics
The Constants class cannot be instantiated. This class has one public variable and two public accessor methods; each is static and final. The constant value associated with the variable, as well as the values returned by the methods, may be useful in the discovery process.
The value of the discoveryPort constant serves two purposes:
The UDP port number over which the multicast request and announcement protocols operate
The TCP port number over which the unicast discovery protocol operates by default
The getRequestAddress method returns an instance of InetAddress that contains the address of the multicast group over which the multicast request protocol takes place.
The getAnnouncementAddress method returns an instance of InetAddress that contains the address of the multicast group over which the multicast announcement protocol takes place.
Note that either getRequestAddress or getAnnouncementAddress may throw an UnknownHostException if called in a circumstance under which multicast address resolution is not permitted.
DU.6.2. The OutgoingMulticastRequest Utility
DU.6.2.1. Overview
The OutgoingMulticastRequest class provides facilities for marshalling multicast discovery requests into a form suitable for transmission over a network for the purposes of announcing one’s interest in discovering a lookup service. This class is useful when building components that participate in the multicast request protocol as part of a group discovery mechanism. This utility should be viewed from the perspective of an entity that wishes to transmit multicast requests in order to discover a lookup service belonging to a set of groups in which the entity is interested.
DU.6.2.2. Other Types
The types defined in the specification of the OutgoingMulticastRequest utility class are in the net.jini.discovery package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
net.jini.core.discovery.ServiceID java.io.IOException java.net.DatagramPacket java.net.InetAddress
DU.6.2.3. The Interface
The public methods provided by the OutgoingMulticastRequest class are as follows:
package net.jini.discovery;
public class OutgoingMulticastRequest {
public static DatagramPacket[] marshal(int port,
String[] groups,
ServiceID[] heard)
throws IOException {...}
} DU.6.2.4. The Semantics
The OutgoingMulticastRequest class cannot be instantiated. This class has only one public method, which is static.
The marshal method takes as input the following arguments, none of which may be null:
The port to which respondents should connect in order to start unicast discovery
A String array, none of whose elements may be null, in which each element is the name of a group the requesting entity is interested in discovering
An array of ServiceID objects, none of whose elements may be null, in which each element corresponds to a lookup service the requesting entity has already heard from
Since implementations are not required to check for duplicated elements, the arguments represented as arrays must not contain such elements.
The marshal method returns an array whose elements are instances of DatagramPacket. The array returned will always contain at least one element, and will contain more if the request is not small enough to fit in a single packet. The array returned by this method is fully initialized; it contains a multicast request as payload and is ready to send over the network.
In the event of error, the marshal method may throw an IOException if marshalling fails. In some instances the exception thrown may be a more specific sub-class of that exception.
DU.6.3. The IncomingMulticastRequest Utility
DU.6.3.1. Overview
The IncomingMulticastRequest class provides facilities that are useful when a requesting entity’s announced interest in discovering a lookup service is received. The facilities provided by this class encapsulate the details of the process of unmarshalling such received multicast discovery requests into a form in which the individual parameters of the request may be easily accessed. This class is useful when building components that participate in the multicast request protocol as part of a group discovery mechanism, where an entity that uses such a component wishes to receive multicast requests in order to be discovered through its group membership; for example, an entity such as a lookup service.
DU.6.3.2. Other Types
The types defined in the specification of the IncomingMulticastRequest utility class are in the net.jini.discovery package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
net.jini.core.discovery.ServiceID java.io.IOException java.net.DatagramPacket java.net.InetAddress
DU.6.3.3. The Interface
The public methods provided by the IncomingMulticastRequest class are as follows:
package net.jini.discovery;
public class IncomingMulticastRequest {
public IncomingMulticastRequest(DatagramPacket dgram)
throws IOException {...}
public InetAddress getAddress() {...}
public int getPort() {...}
public String[] getGroups() {...}
public ServiceID[] getServiceIDs() {...}
} DU.6.3.4. The Semantics
Including the constructor, the IncomingMulticastRequest class defines five new public methods.
The equals method for this class returns true if and only if two instances of this class have the same address, port, groups, and service ID values.
The constructor of the IncomingMulticastRequest class takes a single input parameter: an instance of DatagramPacket. The payload of this parameter is assumed to contain nothing but a marshalled discovery request.
If the marshalled request contained in the input parameter is corrupt, an IOException or a ClassNotFoundException will be thrown. In some such instances, a more specific subclass of either exception may be thrown that will give more detailed information.
The getAddress method returns an instance of InetAddress that represents the address of the host to contact in order to start unicast discovery.
The getPort method returns an int value that is the port number to connect to on the remote host in order to start unicast discovery.
The getGroups method returns an array consisting of the names of the groups in which the requesting entity (the originator of this request) is interested. The array returned by this method may be of zero length, none of its elements will be null, and elements in the returned array may or may not be duplicated. Furthermore, the set reflected in the returned array may not be complete, but other incoming packets should contain the rest of the set.
The getServiceIDs method returns an array of ServiceID instances in which each element of the array corresponds to a lookup service from which the requesting entity has already heard. The array returned by this method may be of zero length, none of its elements will be null, and elements in the returned array may or may not be duplicated. Furthermore, the set returned by this method may not be complete. That is, there may be more lookup services from which the requesting entity has already heard, but the set returned by this method will not exceed the capacity of a packet.
DU.6.4. The OutgoingMulticastAnnouncement Utility
DU.6.4.1. Overview
The OutgoingMulticastAnnouncement class encapsulates the details of the process of marshalling multicast discovery announcements into a form suitable for transmission over a network for the purposes of announcing the availability of a lookup service to interested parties. This class is useful when building components that participate in the multicast announcement protocol as part of a group discovery mechanism. This utility should be viewed from the perspective of an entity that wishes to transmit multicast announcements in order to be discovered as a lookup service belonging to a set of groups in which other discovering entities may be interested.
DU.6.4.2. Other Types
The types defined in the specification of the OutgoingMulticastAnnouncement utility class are in the net.jini.discovery package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
net.jini.core.discovery.LookupLocator net.jini.core.discovery.ServiceID java.io.IOException java.net.DatagramPacket
DU.6.4.3. The Interface
The public methods provided by the OutgoingMulticastAnnouncement class are as follows:
package net.jini.discovery;
public class OutgoingMulticastAnnouncement {
public static DatagramPacket[] marshal(ServiceID id,
LookupLocator loc,
String[]groups)
throws IOException {...}
} DU.6.4.4. The Semantics
The OutgoingMulticastAnnouncement class cannot be instantiated. This class has only one public method, which is static.
The marshal method takes as input the following arguments, none of which may be null:
The instance of ServiceID that corresponds to the lookup service being advertised
The instance of LookupLocator through which the lookup service being advertised may be discovered through unicast discovery
A non-null String array, none of whose elements may be null, in which each element is the name of a group in which the lookup service being advertised is a member
The marshal method returns an array whose elements are instances of DatagramPacket, the contents of which represents a marshalled multicast announcement. The packets created by this method, as represented by the elements of the returned array, are guaranteed to contain all of the groups in which the lookup service being advertised is a member. Note that the set of groups reflected in the returned collection of datagram packets may be distributed among those packets.
Each element of the array returned by this method is initialized such that it is ready for transmission to the appropriate multicast address and UDP port.
In the event of error, the marshal method may throw an IOException if marshalling fails. In some instances, the exception thrown may be a more specific subclass of that exception.
DU.6.5. The IncomingMulticastAnnouncement Utility
DU.6.5.1. Overview
The IncomingMulticastAnnouncement class encapsulates the details of the process of unmarshalling multicast discovery announcements into a form in which the individual parameters of the announcement may be easily accessed. This class is useful when building components that participate in the multicast announcement protocol as part of a group discovery mechanism. This utility should be viewed from the perspective of an entity that wishes to receive multicast announcements in order to discover a lookup service belonging to a set of groups in which the entity is interested.
DU.6.5.2. Other Types
The types defined in the specification of the IncomingMulticastAnnouncement utility class are in the net.jini.discovery package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
net.jini.core.discovery.LookupLocator net.jini.core.discovery.ServiceID java.io.IOException java.net.DatagramPacket
DU.6.5.3. The Interface
The public methods provided by the IncomingMulticastAnnouncement class are as follows:
package net.jini.discovery;
public class IncomingMulticastAnnouncement {
public IncomingMulticastAnnouncement(DatagramPacket p)
throws IOException {...}
public ServiceID getServiceID() {...}
public LookupLocator getLocator() {...}
public String[] getGroups() {...}
} DU.6.5.4. The Semantics
Including the constructor, the IncomingMulticastAnnouncement class defines four new public methods.
The equals method for this class returns true if and only if two instances of this class have the same service ID values.
The constructor of the IncomingMulticastAnnouncement class takes a single input parameter: an instance of DatagramPacket. The constructor attempts to unmarshal the input parameter, storing the results in the various fields of this class.
If the contents of the datagram packet cannot be successfully unmarshalled, either an IOException or a ClassNotFoundException is thrown. In some such instances, a more specific subclass of either exception may be thrown that will give more detailed information.
The getServiceID method returns the ServiceID instance corresponding to the lookup service that sent the announcement.
The getLocator method returns the LookupLocator instance corresponding to the lookup service that sent the announcement. It is through the object returned by this method that the lookup service may be discovered via unicast discovery.
The getGroups method returns an array consisting of the names of the groups in which the lookup service that sent the announcement is a member. The array returned by this method is never null, will contain no null elements, or may be empty. Additionally, elements in the returned array may or may not be duplicated.
DU.6.6. The OutgoingUnicastRequest Utility
DU.6.6.1. Overview
The OutgoingUnicastRequest class encapsulates the details of the process of marshalling unicast discovery requests into a form suitable for transmission over a network to attempt discovery of a specific lookup service. This class is useful when building components that participate in the unicast request protocol as part of either a group or a locator discovery mechanism. This utility should be viewed from the perspective of an entity that wishes to transmit unicast requests in order to discover a specific lookup service in which the entity is interested.
DU.6.6.2. Other Types
The types defined in the specification of the OutgoingUnicastRequest utility class are in the net.jini.discovery package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
java.io.IOException java.io.OutputStream
DU.6.6.3. The Interface
The public methods provided by the OutgoingUnicastRequest class are as follows:
package net.jini.discovery;
public class OutgoingUnicastRequest {
public static void marshal(OutputStream str)
throws IOException {...}
} DU.6.6.4. The Semantics
The OutgoingUnicastRequest class cannot be instantiated. This class has only one public method, which is static.
The marshal method takes only one parameter as input: an instance of OutputStream, which is the stream to which the unicast request is written. After the unicast request is written to the stream, the stream is flushed.
In the event of error, the marshal method may throw an IOException if writing to the stream fails. In some instances, the exception thrown may be a more specific subclass of that exception.
DU.6.7. The IncomingUnicastRequest Utility
DU.6.7.1. Overview
The IncomingUnicastRequest class encapsulates the details of the process of unmarshalling unicast discovery requests into a form in which the individual parameters of the request may be easily accessed. This class is useful when building components that participate in the unicast request protocol as part of either a group or a locator discovery mechanism. This utility should be viewed from the perspective of an entity—such as a lookup service—that wishes to receive unicast requests in order to be discovered through direct, unicast communication.
DU.6.7.2. Other Types
The types defined in the specification of the IncomingUnicastRequest utility class are in the net.jini.discovery package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
java.io.InputStream java.io.IOException
DU.6.7.3. The Interface
The public methods provided by the IncomingUnicastRequest class are as follows:
package net.jini.discovery;
public class IncomingUnicastRequest {
public IncomingUnicastRequest(InputStream str)
throws IOException {...}
} DU.6.7.4. The Semantics
The only new public method defined by the IncomingUnicastRequest class is the constructor.
The constructor of the IncomingUnicastRequest class takes a single input parameter: an instance of InputStream, which is the stream from which the unicast request is read.
In the event of error, an IOException may be thrown if reading from the stream fails. In some instances, the exception thrown may be a more specific subclass of that exception.
DU.6.8. The OutgoingUnicastResponse Utility
DU.6.8.1. Overview
The OutgoingUnicastResponse class encapsulates the details of the process of marshalling a unicast discovery response into a form suitable for transmission over a network to respond to a unicast discovery request. This class is useful when building components that participate in the unicast request protocol as part of either a group or a locator discovery mechanism. This utility should be viewed from the perspective of a entity—such as a lookup service—that wishes to transmit responses to unicast requests in order to be discovered through direct, unicast communication.
DU.6.8.2. Other Types
The types defined in the specification of the OutgoingUnicastResponse utility class are in the net.jini.discovery package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
net.jini.core.lookup.ServiceRegistrar java.io.IOException java.io.OutputStream
DU.6.8.3. The Interface
The public methods provided by the OutgoingUnicastResponse class are as follows:
package net.jini.discovery;
public class OutgoingUnicastResponse {
public static void marshal(OutputStream s,
ServiceRegistrar reg
String[] groups)
throws IOException {...}
} DU.6.8.4. The Semantics
The OutgoingUnicastResponse class cannot be instantiated. This class has only one public method, which is static.
The marshal method takes as input the following arguments, none of which may be null:
An instance of OutputStream, which is the stream to which the unicast response is written.
An instance of ServiceRegistrar that references the proxy to the lookup service that will be marshalled and written to the stream.
A non-null String array, none of whose elements may be null, in which each element is the name of a group in which the lookup service referenced by the reg parameter is a member. Note that duplicate elements are allowed in this parameter.
The marshal method marshals the reg parameter and writes the result to the stream. It then writes each element of the groups parameter to the stream. After the complete unicast response is written to the stream, the stream is flushed.
This method may throw an IOException if a failure occurs while marshalling or writing to the stream. In some instances, the exception thrown may be a more specific subclass of that exception.
DU.6.9. The IncomingUnicastResponse Utility
DU.6.9.1. Overview
The IncomingUnicastResponse class encapsulates the details of the process of unmarshalling a unicast discovery response into a form in which the individual parameters of the request may be easily accessed. This class is useful when building components that participate in the unicast request protocol as part of either a group or a locator discovery mechanism. This utility should be viewed from the perspective of an entity that wishes to receive unicast responses in order to discover lookup services through direct, unicast communication.
DU.6.9.2. Other Types
The types defined in the specification of the IncomingUnicastResponse utility class are in the net.jini.discovery package. The following additional types may also be referenced in this specification. Whenever referenced, these object types will be referenced in unqualified form:
net.jini.core.lookup.ServiceRegistrar java.io.InputStream java.io.IOException
DU.6.9.3. The Interface
The public methods provided by the IncomingUnicastResponse class are as follows:
package net.jini.discovery;
public class IncomingUnicastResponse {
public IncomingUnicastResponse(InputStream s)
throws IOException, ClassNotFoundException {...}
public ServiceRegistrar getRegistrar() {...}
public String[] getGroups() {...}
} DU.6.9.4. The Semantics
Including the constructor, the IncomingUnicastResponse class defines three new methods.
The equals method for this class returns true if and only if two instances of this class reference the same lookup service proxy (registrar).
The constructor of the IncomingUnicastResponse class takes a single input parameter: an instance of InputStream, which is the stream from which the contents of the unicast response is read.
An IOException may be thrown if reading from the stream fails. A ClassNotFoundException may be thrown if failure occurs while unmarshalling the proxy to the lookup service contained in the unicast response. In some such instances, a more specific subclass of either exception may be thrown that will give more detailed information.
The getRegistrar method returns an instance of ServiceRegistrar that references the proxy to the lookup service sent in the unicast response.
The getGroups method returns an array consisting of the names of the groups in which the lookup service referenced in the response is a member. The array returned by this method is never null, will contain no null elements, or may be empty. Additionally, elements in the returned array may or may not be duplicated.