United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4702310 Incorrect documentation for MulticastSocket.joinGroup/leaveGroup.
JDK-4702310 : Incorrect documentation for MulticastSocket.joinGroup/leaveGroup.

Details
Type:
Bug
Submit Date:
2002-06-14
Status:
Closed
Updated Date:
2002-06-14
Project Name:
JDK
Resolved Date:
2002-06-14
Component:
core-libs
OS:
windows_nt
Sub-Component:
java.net
CPU:
x86
Priority:
P4
Resolution:
Duplicate
Affected Versions:
1.4.0
Fixed Versions:

Related Reports
Duplicate:

Sub Tasks

Description

Name: rmT116609			Date: 06/14/2002


FULL PRODUCT VERSION :
java version "1.4.0_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0_01-b03)
Java HotSpot(TM) Client VM (build 1.4.0_01-b03, mixed mode)

DESCRIPTION OF THE PROBLEM :
The Javadoc for MulticastSocket.joinGroup, 2-parameter form, describes the 2nd parameter as 'netIf - specifies the local interface to receive multicast datagram packets'.

The corresponding documentation for MulticastSocket.leaveGroup just describes the 2nd parameter as 'netIf - specifies the local interface'.

Both are incorrect. In both cases, 'netIf' specifies the local interface via which the IGMP 'join' or 'leave' request (if any) is sent.

This is a fairly serious error, as it (a) gives the impression that joinGroup overrides the bind address, and (b) acts to prevent correct usage of joinGroup/leaveGroup in multihomed hosts, where you typically have to join & leave via all interfaces. Indeed this issue, or the issue that the
kernel only does unicast routing for multicasts by default, should be mentioned. This also applies to setInterface/setNetworkInterface, send, and the class
description.


STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :

http://java.sun.com/j2se/1.4/docs/api/java/net/MulticastSocket.html#joinGroup(java.net.SocketAddress, java.net.NetworkInterface)

http://java.sun.com/j2se/1.4/docs/api/java/net/MulticastSocket.html#leaveGroup(java.net.SocketAddress, java.net.NetworkInterface)
(Review ID: 153546) 
======================================================================

                                    

Comments
EVALUATION


Yes, the joinGroup/leaveGroup specification needs to clearly indicate that
the specified network interface is for joining the group. These, and a list
of other specification issues, are being tracked in 4701650.
###@###.### 2002-06-14
                                     
2002-06-14



Hardware and Software, Engineered to Work Together