Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8235423

MulticastSocket joinGroup/leaveGroup do not specify their behavior when the outgoing interface has not been set

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 14
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      There is no behavior change. This is just a clarification of the specification.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      MulticastSocket joinGroup/leaveGroup do not specify their behavior when the outgoing interface has not been set.

      Problem

      The current javadoc is unclear on the behaviour of the 2-arg joinGroup/leaveGroup methods if null is given for the NetworkInterface parameter and no interface has been set. Similarly, the javadoc for the methods getInterface() and getNetworkInterface() do not specify what is returned when no NetworkInterface has previously been set.

      Solution

      This fix clarifies the javadoc by describing the behaviour of the methods when null is passed for the NetworkInterface parameter for the 2-arg joinGroup/leaveGroup methods. It also clarifies what is returned from getInterface and getNetworkInterface when no NetworkInterface has been previously set.

      Specification

      MulticastSocket::joinGroup

            * @param netIf specifies the local interface to receive multicast
            *        datagram packets, or {@code null} to defer to the interface set by
            *       {@link MulticastSocket#setInterface(InetAddress)} or
      -     *       {@link MulticastSocket#setNetworkInterface(NetworkInterface)}
      -     *
      +     *        {@link MulticastSocket#setNetworkInterface(NetworkInterface)}.
      +     *        If {@code null} is given and no interface has been set, the behaviour is
      +     *        unspecified: any interface may be selected or the operation may fail
      +     *        with a SocketException.

      MulticastSocket::leaveGroup

            * @param netIf specifies the local interface or {@code null} to defer
      -     *             to the interface set by
      -     *             {@link MulticastSocket#setInterface(InetAddress)} or
      -     *             {@link MulticastSocket#setNetworkInterface(NetworkInterface)}
      +     *        to the interface set by {@link MulticastSocket#setInterface(InetAddress)}
      +     *        or {@link MulticastSocket#setNetworkInterface(NetworkInterface)}. If
      +     *        {@code null} is given and no interface has been set, the behaviour is
      +     *        unspecified: any interface may be selected or the operation may fail
      +     *        with a SocketException.

      MulticastSocket::getInterface

           * @return An {@code InetAddress} representing
            *  the address of the network interface used for
      -     *  multicast packets.
      -     *
      +     *  multicast packets, or if no interface has been set,
      +     *  an {@code InetAddress} representing any local address.

      MulticastSocket::getNetworkInterface

      -     * @return the multicast {@code NetworkInterface} currently set
      +     * @return The multicast {@code NetworkInterface} currently set. A placeholder
      +     *         NetworkInterface is returned when there is no interface set; it has
      +     *         a single InetAddress to represent any local address.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                pconcannon Patrick Concannon
                Reporter:
                alanb Alan Bateman
                Reviewed By:
                Alan Bateman, Chris Hegarty, Daniel Fuchs
              • Votes:
                0 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: