archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 23:04:50 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8233319: Deprecate MulticastSocket methods that operate on java.net.InetAddress

Browse source 
Deprecate any method that operates on InetAddress as well as getLoopbackMode and setLoopbackMode

Reviewed-by: chegar, dfuchs, alanb
This commit is contained in:
Julia Boes 2019-12-09 12:06:26 +00:00
parent 9cabfa82ff
commit 3ea25ecdfe
2 changed files with 104 additions and 90 deletions
Download patch file Download diff file Expand all files Collapse all files

190
src/java.base/share/classes/java/net/MulticastSocket.java
View file

@ -29,17 +29,16 @@ import java.io.IOException;
import java.util.Collections; import java.util.Collections;
import java.util.Enumeration; import java.util.Enumeration;
import java.util.Set; import java.util.Set;
import java.net.PortUnreachableException;
/** /**
* The multicast datagram socket class is useful for sending * 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 * a (UDP) DatagramSocket, with additional capabilities for
* joining "groups" of other multicast hosts on the internet. * joining "groups" of other multicast hosts on the internet.
* <P> * <P>
* A multicast group is specified by a class D IP address * A multicast group is specified by a class D IP address
* and by a standard UDP port number. Class D IP addresses * 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. * inclusive. The address 224.0.0.0 is reserved and should not be used.
* <P> * <P>
* One would join a multicast group by first creating a MulticastSocket * One would join a multicast group by first creating a MulticastSocket
@ -50,9 +49,12 @@ import java.net.PortUnreachableException;
* // join a Multicast group and send the group salutations * // join a Multicast group and send the group salutations
* ... * ...
* String msg = "Hello"; * 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); * MulticastSocket s = new MulticastSocket(6789);
* s.joinGroup(group); *
* s.joinGroup(group, netIf);
* byte[] msgBytes = msg.getBytes(StandardCharsets.UTF_8); * byte[] msgBytes = msg.getBytes(StandardCharsets.UTF_8);
* DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length, * DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length,
* group, 6789); * group, 6789);
@ -63,25 +65,24 @@ import java.net.PortUnreachableException;
* s.receive(recv); * s.receive(recv);
* ... * ...
* // OK, I'm done talking - leave the group... * // OK, I'm done talking - leave the group...
* s.leaveGroup(group); * s.leaveGroup(group, netIf);
* </PRE> * </PRE>
* *
* When one sends a message to a multicast group, <B>all</B> subscribing * When one sends a message to a multicast group, <B>all</B> subscribing
* recipients to that host and port receive the message (within the * 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. * be a member of the multicast group to send messages to it.
* <P> * <P>
* When a socket subscribes to a multicast group/port, it receives * When a socket subscribes to a multicast group/port, it receives
* datagrams sent by other hosts to the group/port, as do all other * datagrams sent by other hosts to the group/port, as do all other
* members of the group and port. A socket relinquishes membership * members of the group and port. A socket relinquishes membership
* in a group by the leaveGroup(InetAddress addr) method. <B> * in a group by the leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)
* Multiple MulticastSocket's</B> may subscribe to a multicast group * method.
* <B>Multiple MulticastSockets</B> may subscribe to a multicast group
* and port concurrently, and they will all receive group datagrams. * and port concurrently, and they will all receive group datagrams.
* <P>
* Currently applets are not allowed to use multicast sockets.
* *
* @author Pavani Diwanji * @author Pavani Diwanji
* @since 1.1 * @since 1.1
*/ */
public class MulticastSocket extends DatagramSocket { public class MulticastSocket extends DatagramSocket {
@ -287,20 +288,21 @@ public class MulticastSocket extends DatagramSocket {
* {@code setInterface} or {@code setNetworkInterface}. * {@code setInterface} or {@code setNetworkInterface}.
* *
* <p>If there is a security manager, this method first * <p>If there is a security manager, this method first
* calls its {@code checkMulticast} method * calls its {@code checkMulticast} method with the
* with the {@code mcastaddr} argument * {@code mcastaddr} argument as its argument.
* as its argument.
* *
* @param mcastaddr is the multicast address to join * @param mcastaddr is the multicast address to join
* * @throws IOException if there is an error joining,
* @throws IOException if there is an error joining, or when the address * or when the address is not a multicast address,
* is not a multicast address, or the platform does not support * or the platform does not support multicasting
* multicasting * @throws SecurityException if a security manager exists and its
* @throws SecurityException if a security manager exists and its * {@code checkMulticast} method doesn't allow the join.
* {@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
* @see SecurityManager#checkMulticast(InetAddress) * {@link #joinGroup(SocketAddress, NetworkInterface)} instead.
* @see SecurityManager#checkMulticast(InetAddress)
*/ */
@Deprecated(since="14")
public void joinGroup(InetAddress mcastaddr) throws IOException { public void joinGroup(InetAddress mcastaddr) throws IOException {
if (isClosed()) { if (isClosed()) {
throw new SocketException("Socket is closed"); throw new SocketException("Socket is closed");
@ -334,18 +336,20 @@ public class MulticastSocket extends DatagramSocket {
* {@code setInterface} or {@code setNetworkInterface}. * {@code setInterface} or {@code setNetworkInterface}.
* *
* <p>If there is a security manager, this method first * <p>If there is a security manager, this method first
* calls its {@code checkMulticast} method * calls its {@code checkMulticast} method with the
* with the {@code mcastaddr} argument * {@code mcastaddr} argument as its argument.
* as its argument.
* *
* @param mcastaddr is the multicast address to leave * @param mcastaddr is the multicast address to leave
* @throws IOException if there is an error leaving * @throws IOException if there is an error leaving
* or when the address is not a multicast address. * or when the address is not a multicast address.
* @throws SecurityException if a security manager exists and its * @throws SecurityException if a security manager exists and its
* {@code checkMulticast} method doesn't allow the operation. * {@code checkMulticast} method doesn't allow the operation.
* * @deprecated This method does not accept the network interface on which
* @see SecurityManager#checkMulticast(InetAddress) * 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 { public void leaveGroup(InetAddress mcastaddr) throws IOException {
if (isClosed()) { if (isClosed()) {
throw new SocketException("Socket is closed"); throw new SocketException("Socket is closed");
@ -372,22 +376,20 @@ public class MulticastSocket extends DatagramSocket {
* with the {@code mcastaddr} argument * with the {@code mcastaddr} argument
* as its argument. * as its argument.
* *
* @param mcastaddr is the multicast address to join * @param mcastaddr is the multicast address to join
* @param netIf specifies the local interface to receive multicast * @param netIf specifies the local interface to receive multicast
* datagram packets, or <i>null</i> to defer to the interface set by * datagram packets, or <i>null</i> to defer to the interface set by
* {@link MulticastSocket#setInterface(InetAddress)} or * {@link MulticastSocket#setInterface(InetAddress)} or
* {@link MulticastSocket#setNetworkInterface(NetworkInterface)} * {@link MulticastSocket#setNetworkInterface(NetworkInterface)}
* * @throws IOException if there is an error joining, or when the address
* @throws IOException if there is an error joining, or when the address * is not a multicast address, or the platform does not support
* is not a multicast address, or the platform does not support * multicasting
* multicasting * @throws SecurityException if a security manager exists and its
* @throws SecurityException if a security manager exists and its * {@code checkMulticast} method doesn't allow the join.
* {@code checkMulticast} method doesn't allow the join. * @throws IllegalArgumentException if mcastaddr is null or is a
* @throws IllegalArgumentException if mcastaddr is null or is a * SocketAddress subclass not supported by this socket
* SocketAddress subclass not supported by this socket * @see SecurityManager#checkMulticast(InetAddress)
* * @since 1.4
* @see SecurityManager#checkMulticast(InetAddress)
* @since 1.4
*/ */
public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf) public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf)
throws IOException { throws IOException {
@ -417,24 +419,22 @@ public class MulticastSocket extends DatagramSocket {
* Leave a multicast group on a specified local interface. * Leave a multicast group on a specified local interface.
* *
* <p>If there is a security manager, this method first * <p>If there is a security manager, this method first
* calls its {@code checkMulticast} method * calls its {@code checkMulticast} method with the
* with the {@code mcastaddr} argument * {@code mcastaddr} argument as its argument.
* as its argument.
* *
* @param mcastaddr is the multicast address to leave * @param mcastaddr is the multicast address to leave
* @param netIf specifies the local interface or <i>null</i> to defer * @param netIf specifies the local interface or <i>null</i> to defer
* to the interface set by * to the interface set by
* {@link MulticastSocket#setInterface(InetAddress)} or * {@link MulticastSocket#setInterface(InetAddress)} or
* {@link MulticastSocket#setNetworkInterface(NetworkInterface)} * {@link MulticastSocket#setNetworkInterface(NetworkInterface)}
* @throws IOException if there is an error leaving * @throws IOException if there is an error leaving or when the address
* or when the address is not a multicast address. * is not a multicast address.
* @throws SecurityException if a security manager exists and its * @throws SecurityException if a security manager exists and its
* {@code checkMulticast} method doesn't allow the operation. * {@code checkMulticast} method doesn't allow the operation.
* @throws IllegalArgumentException if mcastaddr is null or is a * @throws IllegalArgumentException if mcastaddr is null or is a
* SocketAddress subclass not supported by this socket * SocketAddress subclass not supported by this socket.
* * @see SecurityManager#checkMulticast(InetAddress)
* @see SecurityManager#checkMulticast(InetAddress) * @since 1.4
* @since 1.4
*/ */
public void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf) public void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)
throws IOException { throws IOException {
@ -464,11 +464,16 @@ public class MulticastSocket extends DatagramSocket {
* Set the multicast network interface used by methods * Set the multicast network interface used by methods
* whose behavior would be affected by the value of the * whose behavior would be affected by the value of the
* network interface. Useful for multihomed hosts. * network interface. Useful for multihomed hosts.
* @param inf the InetAddress *
* @throws SocketException if there is an error in * @param inf the InetAddress
* the underlying protocol, such as a TCP error. * @throws SocketException if there is an error in
* @see #getInterface() * 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 { public void setInterface(InetAddress inf) throws SocketException {
if (isClosed()) { if (isClosed()) {
throw new SocketException("Socket is closed"); throw new SocketException("Socket is closed");
@ -485,15 +490,16 @@ public class MulticastSocket extends DatagramSocket {
* Retrieve the address of the network interface used for * Retrieve the address of the network interface used for
* multicast packets. * multicast packets.
* *
* @return An {@code InetAddress} representing * @return An {@code InetAddress} representing the address
* the address of the network interface used for * of the network interface used for multicast packets.
* multicast packets. * @throws SocketException if there is an error in the
* * underlying protocol, such as a TCP error.
* @throws SocketException if there is an error in * @deprecated The network interface may not be uniquely identified by
* the underlying protocol, such as a TCP error. * the InetAddress returned.
* * Use {@link #getNetworkInterface()} instead.
* @see #setInterface(java.net.InetAddress) * @see #setInterface(java.net.InetAddress)
*/ */
@Deprecated(since="14")
public InetAddress getInterface() throws SocketException { public InetAddress getInterface() throws SocketException {
if (isClosed()) { if (isClosed()) {
throw new SocketException("Socket is closed"); throw new SocketException("Socket is closed");
@ -594,11 +600,17 @@ public class MulticastSocket extends DatagramSocket {
* <p>Because this option is a hint, applications that want to * <p>Because this option is a hint, applications that want to
* verify what loopback mode is set to should call * verify what loopback mode is set to should call
* {@link #getLoopbackMode()} * {@link #getLoopbackMode()}
* @param disable {@code true} to disable the LoopbackMode * @param disable {@code true} to disable the LoopbackMode
* @throws SocketException if an error occurs while setting the value * @throws SocketException if an error occurs while setting the value
* @since 1.4 * @since 1.4
* @see #getLoopbackMode * @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 { public void setLoopbackMode(boolean disable) throws SocketException {
getImpl().setOption(SocketOptions.IP_MULTICAST_LOOP, Boolean.valueOf(disable)); getImpl().setOption(SocketOptions.IP_MULTICAST_LOOP, Boolean.valueOf(disable));
} }
@ -606,11 +618,15 @@ public class MulticastSocket extends DatagramSocket {
/** /**
* Get the setting for local loopback of multicast datagrams. * Get the setting for local loopback of multicast datagrams.
* *
* @throws SocketException if an error occurs while getting the value * @throws SocketException if an error occurs while getting the value
* @return true if the LoopbackMode has been disabled * @return true if the LoopbackMode has been disabled
* @since 1.4 * @since 1.4
* @see #setLoopbackMode * @deprecated Use {@link #getOption(SocketOption)} with
* {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP}
* instead.
* @see #setLoopbackMode
*/ */
@Deprecated(since="14")
public boolean getLoopbackMode() throws SocketException { public boolean getLoopbackMode() throws SocketException {
return ((Boolean)getImpl().getOption(SocketOptions.IP_MULTICAST_LOOP)).booleanValue(); return ((Boolean)getImpl().getOption(SocketOptions.IP_MULTICAST_LOOP)).booleanValue();
} }

4
src/java.base/share/classes/java/net/StandardSocketOptions.java
View file

@ -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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -291,7 +291,6 @@ public final class StandardSocketOptions {
* is system dependent. * is system dependent.
* *
* @see java.nio.channels.MulticastChannel * @see java.nio.channels.MulticastChannel
* @see MulticastSocket#setInterface
*/ */
public static final SocketOption<NetworkInterface> IP_MULTICAST_IF = public static final SocketOption<NetworkInterface> IP_MULTICAST_IF =
new StdSocketOption<NetworkInterface>("IP_MULTICAST_IF", NetworkInterface.class); new StdSocketOption<NetworkInterface>("IP_MULTICAST_IF", NetworkInterface.class);
@ -343,7 +342,6 @@ public final class StandardSocketOptions {
* binding the socket is system dependent. * binding the socket is system dependent.
* *
* @see java.nio.channels.MulticastChannel * @see java.nio.channels.MulticastChannel
* @see MulticastSocket#setLoopbackMode
*/ */
public static final SocketOption<Boolean> IP_MULTICAST_LOOP = public static final SocketOption<Boolean> IP_MULTICAST_LOOP =
new StdSocketOption<Boolean>("IP_MULTICAST_LOOP", Boolean.class); new StdSocketOption<Boolean>("IP_MULTICAST_LOOP", Boolean.class);