OpenJDK / jdk / jdk

changeset 57282:c445504316e4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
8233319: Deprecate MulticastSocket methods that operate on java.net.InetAddress Summary: Deprecate any method that operates on InetAddress as well as getLoopbackMode and setLoopbackMode Reviewed-by: chegar, dfuchs, alanb
author jboes
date Mon, 09 Dec 2019 12:06:26 +0000
parents 45fceff98bb5
children 5e94d60e5dd3
files src/java.base/share/classes/java/net/MulticastSocket.java src/java.base/share/classes/java/net/StandardSocketOptions.java
diffstat 2 files changed, 104 insertions(+), 90 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/net/MulticastSocket.java	Mon Dec 09 10:26:41 2019 +0100
+++ b/src/java.base/share/classes/java/net/MulticastSocket.java	Mon Dec 09 12:06:26 2019 +0000
@@ -29,17 +29,16 @@
 import java.util.Collections;
 import java.util.Enumeration;
 import java.util.Set;
-import java.net.PortUnreachableException;
 
 /**
  * The multicast datagram socket class is useful for sending
- * and receiving IP multicast packets.  A MulticastSocket is
+ * and receiving IP multicast packets. A MulticastSocket is
  * a (UDP) DatagramSocket, with additional capabilities for
  * joining "groups" of other multicast hosts on the internet.
  * <P>
  * A multicast group is specified by a class D IP address
  * and by a standard UDP port number. Class D IP addresses
- * are in the range <CODE>224.0.0.0</CODE> to <CODE>239.255.255.255</CODE>,
+ * are in the range {@code 224.0.0.0} to {@code 239.255.255.255},
  * inclusive. The address 224.0.0.0 is reserved and should not be used.
  * <P>
  * One would join a multicast group by first creating a MulticastSocket
@@ -50,9 +49,12 @@
  * // join a Multicast group and send the group salutations
  * ...
  * String msg = "Hello";
- * InetAddress group = InetAddress.getByName("228.5.6.7");
+ * InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
+ * InetSocketAddress group = new InetSocketAddress(mcastaddr, port);
+ * NetworkInterface netIf = NetworkInterface.getByName("bge0");
  * MulticastSocket s = new MulticastSocket(6789);
- * s.joinGroup(group);
+ *
+ * s.joinGroup(group, netIf);
  * byte[] msgBytes = msg.getBytes(StandardCharsets.UTF_8);
  * DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length,
  *                                        group, 6789);
@@ -63,25 +65,24 @@
  * s.receive(recv);
  * ...
  * // OK, I'm done talking - leave the group...
- * s.leaveGroup(group);
+ * s.leaveGroup(group, netIf);
  * </PRE>
  *
  * When one sends a message to a multicast group, <B>all</B> subscribing
  * recipients to that host and port receive the message (within the
- * time-to-live range of the packet, see below).  The socket needn't
+ * time-to-live range of the packet, see below). The socket needn't
  * be a member of the multicast group to send messages to it.
  * <P>
  * When a socket subscribes to a multicast group/port, it receives
  * datagrams sent by other hosts to the group/port, as do all other
  * members of the group and port.  A socket relinquishes membership
- * in a group by the leaveGroup(InetAddress addr) method.  <B>
- * Multiple MulticastSocket's</B> may subscribe to a multicast group
+ * in a group by the leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)
+ * method.
+ * <B>Multiple MulticastSockets</B> may subscribe to a multicast group
  * and port concurrently, and they will all receive group datagrams.
- * <P>
- * Currently applets are not allowed to use multicast sockets.
  *
  * @author Pavani Diwanji
- * @since  1.1
+ * @since 1.1
  */
 public class MulticastSocket extends DatagramSocket {
 
@@ -287,20 +288,21 @@
      * {@code setInterface} or {@code setNetworkInterface}.
      *
      * <p>If there is a security manager, this method first
-     * calls its {@code checkMulticast} method
-     * with the {@code mcastaddr} argument
-     * as its argument.
-     *
-     * @param mcastaddr is the multicast address to join
+     * calls its {@code checkMulticast} method with the
+     * {@code mcastaddr} argument as its argument.
      *
-     * @throws    IOException if there is an error joining, or when the address
-     *            is not a multicast address, or the platform does not support
-     *            multicasting
-     * @throws     SecurityException  if a security manager exists and its
-     * {@code checkMulticast} method doesn't allow the join.
-     *
-     * @see SecurityManager#checkMulticast(InetAddress)
+     * @param      mcastaddr is the multicast address to join
+     * @throws     IOException if there is an error joining,
+     *             or when the address is not a multicast address,
+     *             or the platform does not support multicasting
+     * @throws     SecurityException if a security manager exists and its
+     *             {@code checkMulticast} method doesn't allow the join.
+     * @deprecated This method does not accept the network interface on
+     *             which to join the multicast group. Use
+     *             {@link #joinGroup(SocketAddress, NetworkInterface)} instead.
+     * @see        SecurityManager#checkMulticast(InetAddress)
      */
+    @Deprecated(since="14")
     public void joinGroup(InetAddress mcastaddr) throws IOException {
         if (isClosed()) {
             throw new SocketException("Socket is closed");
@@ -334,18 +336,20 @@
      * {@code setInterface} or {@code setNetworkInterface}.
      *
      * <p>If there is a security manager, this method first
-     * calls its {@code checkMulticast} method
-     * with the {@code mcastaddr} argument
-     * as its argument.
+     * calls its {@code checkMulticast} method with the
+     * {@code mcastaddr} argument as its argument.
      *
-     * @param mcastaddr is the multicast address to leave
-     * @throws    IOException if there is an error leaving
-     * or when the address is not a multicast address.
-     * @throws     SecurityException  if a security manager exists and its
-     * {@code checkMulticast} method doesn't allow the operation.
-     *
-     * @see SecurityManager#checkMulticast(InetAddress)
+     * @param      mcastaddr is the multicast address to leave
+     * @throws     IOException if there is an error leaving
+     *             or when the address is not a multicast address.
+     * @throws     SecurityException if a security manager exists and its
+     *             {@code checkMulticast} method doesn't allow the operation.
+     * @deprecated This method does not accept the network interface on which
+     *             to leave the multicast group. Use
+     *             {@link #leaveGroup(SocketAddress, NetworkInterface)} instead.
+     * @see        SecurityManager#checkMulticast(InetAddress)
      */
+    @Deprecated(since="14")
     public void leaveGroup(InetAddress mcastaddr) throws IOException {
         if (isClosed()) {
             throw new SocketException("Socket is closed");
@@ -372,22 +376,20 @@
      * with the {@code mcastaddr} argument
      * as its argument.
      *
-     * @param mcastaddr is the multicast address to join
-     * @param netIf specifies the local interface to receive multicast
-     *        datagram packets, or <i>null</i> to defer to the interface set by
-     *       {@link MulticastSocket#setInterface(InetAddress)} or
-     *       {@link MulticastSocket#setNetworkInterface(NetworkInterface)}
-     *
-     * @throws    IOException if there is an error joining, or when the address
-     *            is not a multicast address, or the platform does not support
-     *            multicasting
-     * @throws     SecurityException  if a security manager exists and its
-     * {@code checkMulticast} method doesn't allow the join.
-     * @throws  IllegalArgumentException if mcastaddr is null or is a
-     *          SocketAddress subclass not supported by this socket
-     *
-     * @see SecurityManager#checkMulticast(InetAddress)
-     * @since 1.4
+     * @param  mcastaddr is the multicast address to join
+     * @param  netIf specifies the local interface to receive multicast
+     *         datagram packets, or <i>null</i> to defer to the interface set by
+     *         {@link MulticastSocket#setInterface(InetAddress)} or
+     *         {@link MulticastSocket#setNetworkInterface(NetworkInterface)}
+     * @throws IOException if there is an error joining, or when the address
+     *         is not a multicast address, or the platform does not support
+     *         multicasting
+     * @throws SecurityException if a security manager exists and its
+     *         {@code checkMulticast} method doesn't allow the join.
+     * @throws IllegalArgumentException if mcastaddr is null or is a
+     *         SocketAddress subclass not supported by this socket
+     * @see    SecurityManager#checkMulticast(InetAddress)
+     * @since  1.4
      */
     public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf)
         throws IOException {
@@ -417,24 +419,22 @@
      * Leave a multicast group on a specified local interface.
      *
      * <p>If there is a security manager, this method first
-     * calls its {@code checkMulticast} method
-     * with the {@code mcastaddr} argument
-     * as its argument.
+     * calls its {@code checkMulticast} method with the
+     * {@code mcastaddr} argument as its argument.
      *
-     * @param mcastaddr is the multicast address to leave
-     * @param netIf specifies the local interface or <i>null</i> to defer
-     *             to the interface set by
-     *             {@link MulticastSocket#setInterface(InetAddress)} or
-     *             {@link MulticastSocket#setNetworkInterface(NetworkInterface)}
-     * @throws    IOException if there is an error leaving
-     * or when the address is not a multicast address.
-     * @throws     SecurityException  if a security manager exists and its
-     * {@code checkMulticast} method doesn't allow the operation.
-     * @throws  IllegalArgumentException if mcastaddr is null or is a
-     *          SocketAddress subclass not supported by this socket
-     *
-     * @see SecurityManager#checkMulticast(InetAddress)
-     * @since 1.4
+     * @param  mcastaddr is the multicast address to leave
+     * @param  netIf specifies the local interface or <i>null</i> to defer
+     *         to the interface set by
+     *         {@link MulticastSocket#setInterface(InetAddress)} or
+     *         {@link MulticastSocket#setNetworkInterface(NetworkInterface)}
+     * @throws IOException if there is an error leaving or when the address
+     *         is not a multicast address.
+     * @throws SecurityException if a security manager exists and its
+     *         {@code checkMulticast} method doesn't allow the operation.
+     * @throws IllegalArgumentException if mcastaddr is null or is a
+     *         SocketAddress subclass not supported by this socket.
+     * @see    SecurityManager#checkMulticast(InetAddress)
+     * @since  1.4
      */
     public void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)
         throws IOException {
@@ -464,11 +464,16 @@
      * Set the multicast network interface used by methods
      * whose behavior would be affected by the value of the
      * network interface. Useful for multihomed hosts.
-     * @param inf the InetAddress
-     * @throws    SocketException if there is an error in
-     * the underlying protocol, such as a TCP error.
-     * @see #getInterface()
+     *
+     * @param      inf the InetAddress
+     * @throws     SocketException if there is an error in
+     *             the underlying protocol, such as a TCP error.
+     * @deprecated The InetAddress may not uniquely identify
+     *             the network interface. Use
+     *             {@link #setNetworkInterface(NetworkInterface)} instead.
+     * @see        #getInterface()
      */
+    @Deprecated(since="14")
     public void setInterface(InetAddress inf) throws SocketException {
         if (isClosed()) {
             throw new SocketException("Socket is closed");
@@ -485,15 +490,16 @@
      * Retrieve the address of the network interface used for
      * multicast packets.
      *
-     * @return An {@code InetAddress} representing
-     *  the address of the network interface used for
-     *  multicast packets.
-     *
-     * @throws    SocketException if there is an error in
-     * the underlying protocol, such as a TCP error.
-     *
-     * @see #setInterface(java.net.InetAddress)
+     * @return     An {@code InetAddress} representing the address
+     *             of the network interface used for multicast packets.
+     * @throws     SocketException if there is an error in the
+     *             underlying protocol, such as a TCP error.
+     * @deprecated The network interface may not be uniquely identified by
+     *             the InetAddress returned.
+     *             Use {@link #getNetworkInterface()} instead.
+     * @see        #setInterface(java.net.InetAddress)
      */
+    @Deprecated(since="14")
     public InetAddress getInterface() throws SocketException {
         if (isClosed()) {
             throw new SocketException("Socket is closed");
@@ -594,11 +600,17 @@
      * <p>Because this option is a hint, applications that want to
      * verify what loopback mode is set to should call
      * {@link #getLoopbackMode()}
-     * @param disable {@code true} to disable the LoopbackMode
-     * @throws SocketException if an error occurs while setting the value
-     * @since 1.4
-     * @see #getLoopbackMode
+     * @param      disable {@code true} to disable the LoopbackMode
+     * @throws     SocketException if an error occurs while setting the value
+     * @since      1.4
+     * @deprecated Use {@link #setOption(SocketOption, Object)} with
+     *             {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP}
+     *             instead. The loopback mode is enabled by default,
+     *             {@code MulticastSocket.setOption(StandardSocketOptions.IP_MULTICAST_LOOP, false)}
+     *             disables it.
+     * @see        #getLoopbackMode
      */
+    @Deprecated(since="14")
     public void setLoopbackMode(boolean disable) throws SocketException {
         getImpl().setOption(SocketOptions.IP_MULTICAST_LOOP, Boolean.valueOf(disable));
     }
@@ -606,11 +618,15 @@
     /**
      * Get the setting for local loopback of multicast datagrams.
      *
-     * @throws SocketException  if an error occurs while getting the value
-     * @return true if the LoopbackMode has been disabled
-     * @since 1.4
-     * @see #setLoopbackMode
+     * @throws     SocketException if an error occurs while getting the value
+     * @return     true if the LoopbackMode has been disabled
+     * @since      1.4
+     * @deprecated Use {@link #getOption(SocketOption)} with
+     *             {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP}
+     *             instead.
+     * @see        #setLoopbackMode
      */
+    @Deprecated(since="14")
     public boolean getLoopbackMode() throws SocketException {
         return ((Boolean)getImpl().getOption(SocketOptions.IP_MULTICAST_LOOP)).booleanValue();
     }
--- a/src/java.base/share/classes/java/net/StandardSocketOptions.java	Mon Dec 09 10:26:41 2019 +0100
+++ b/src/java.base/share/classes/java/net/StandardSocketOptions.java	Mon Dec 09 12:06:26 2019 +0000
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2007, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2007, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -291,7 +291,6 @@
      * is system dependent.
      *
      * @see java.nio.channels.MulticastChannel
-     * @see MulticastSocket#setInterface
      */
     public static final SocketOption<NetworkInterface> IP_MULTICAST_IF =
         new StdSocketOption<NetworkInterface>("IP_MULTICAST_IF", NetworkInterface.class);
@@ -343,7 +342,6 @@
      * binding the socket is system dependent.
      *
      * @see java.nio.channels.MulticastChannel
-     *  @see MulticastSocket#setLoopbackMode
      */
     public static final SocketOption<Boolean> IP_MULTICAST_LOOP =
         new StdSocketOption<Boolean>("IP_MULTICAST_LOOP", Boolean.class);
© 2007, Oracle and/or its affiliates
Terms of Use · Privacy · Trademarks