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)
======================================================================