JDK-4702310 : Incorrect documentation for MulticastSocket.joinGroup/leaveGroup.
  • Type: Bug
  • Component: core-libs
  • Sub-Component: java.net
  • Affected Version: 1.4.0
  • Priority: P4
  • Status: Closed
  • Resolution: Duplicate
  • OS: windows_nt
  • CPU: x86
  • Submitted: 2002-06-14
  • Updated: 2002-06-14
  • Resolved: 2002-06-14
Related Reports
Duplicate :  
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