mirror of
https://github.com/openjdk/jdk.git
synced 2025-08-27 06:45:07 +02:00
8237352: Update DatagramSocket to add support for joining multicast groups
Reviewed-by: alanb
This commit is contained in:
Daniel Fuchs
parent
d0a8f2f737
commit
2c28e36454
5 changed files with 931 additions and 111 deletions
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 1995, 2020, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 1995, 2021, 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
|
||||
|
|
@ -28,6 +28,7 @@ package java.net;
|
|||
import java.io.IOException;
|
||||
import java.io.UncheckedIOException;
|
||||
import java.nio.channels.DatagramChannel;
|
||||
import java.nio.channels.MulticastChannel;
|
||||
import java.security.AccessController;
|
||||
import java.security.PrivilegedAction;
|
||||
import java.util.Set;
|
||||
|
|
@ -81,11 +82,11 @@ import sun.nio.ch.DefaultSelectorProvider;
|
|||
* <tbody>
|
||||
* <tr>
|
||||
* <th scope="row"> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </th>
|
||||
* <td> The size of the socket send buffer </td>
|
||||
* <td> The size of the socket send buffer in bytes </td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row"> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </th>
|
||||
* <td> The size of the socket receive buffer </td>
|
||||
* <td> The size of the socket receive buffer in bytes </td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row"> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </th>
|
||||
|
|
@ -102,10 +103,142 @@ import sun.nio.ch.DefaultSelectorProvider;
|
|||
* </tbody>
|
||||
* </table>
|
||||
* </blockquote>
|
||||
* An implementation may also support additional options. In particular an implementation
|
||||
* may support <a href="MulticastSocket.html#MulticastOptions">multicast options</a> which
|
||||
* can be useful when using a plain {@code DatagramSocket} to send datagrams to a
|
||||
* multicast group.
|
||||
* <p> In addition, the {@code DatagramSocket} class defines methods to {@linkplain
|
||||
* #joinGroup(SocketAddress, NetworkInterface) join} and {@linkplain
|
||||
* #leaveGroup(SocketAddress, NetworkInterface) leave} a multicast group, and
|
||||
* supports <a href="DatagramSocket.html#MulticastOptions">multicast options</a> which
|
||||
* are useful when {@linkplain #joinGroup(SocketAddress, NetworkInterface) joining},
|
||||
* {@linkplain #leaveGroup(SocketAddress, NetworkInterface) leaving}, or sending datagrams
|
||||
* to a multicast group.
|
||||
* The following multicast options are supported:
|
||||
* <blockquote>
|
||||
* <a id="MulticastOptions"></a>
|
||||
* <table class="striped">
|
||||
* <caption style="display:none">Multicast options</caption>
|
||||
* <thead>
|
||||
* <tr>
|
||||
* <th scope="col">Option Name</th>
|
||||
* <th scope="col">Description</th>
|
||||
* </tr>
|
||||
* </thead>
|
||||
* <tbody>
|
||||
* <tr>
|
||||
* <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_IF IP_MULTICAST_IF} </th>
|
||||
* <td> The network interface for Internet Protocol (IP) multicast datagrams </td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_TTL
|
||||
* IP_MULTICAST_TTL} </th>
|
||||
* <td> The <em>time-to-live</em> for Internet Protocol (IP) multicast
|
||||
* datagrams </td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP
|
||||
* IP_MULTICAST_LOOP} </th>
|
||||
* <td> Loopback for Internet Protocol (IP) multicast datagrams </td>
|
||||
* </tr>
|
||||
* </tbody>
|
||||
* </table>
|
||||
* </blockquote>
|
||||
* An implementation may also support additional options.
|
||||
*
|
||||
* @apiNote <a id="Multicasting"></a><b>Multicasting with DatagramSocket</b>
|
||||
*
|
||||
* <p> {@link DatagramChannel} implements the {@link MulticastChannel} interface
|
||||
* and provides an alternative API for sending and receiving multicast datagrams.
|
||||
* The {@link MulticastChannel} API supports both {@linkplain
|
||||
* MulticastChannel#join(InetAddress, NetworkInterface) any-source} and
|
||||
* {@linkplain MulticastChannel#join(InetAddress, NetworkInterface, InetAddress)
|
||||
* source-specific} multicast. Consider using {@code DatagramChannel} for
|
||||
* multicasting.
|
||||
*
|
||||
* <p> {@code DatagramSocket} can be used directly for multicasting. However,
|
||||
* contrarily to {@link MulticastSocket}, {@code DatagramSocket} doesn't call the
|
||||
* {@link DatagramSocket#setReuseAddress(boolean)} method to enable the SO_REUSEADDR
|
||||
* socket option by default. If creating a {@code DatagramSocket} intended to
|
||||
* later join a multicast group, the caller should consider explicitly enabling
|
||||
* the SO_REUSEADDR option.
|
||||
*
|
||||
* <p> An instance of {@code DatagramSocket} can be used to send or
|
||||
* receive multicast datagram packets. It is not necessary to join a multicast
|
||||
* group in order to send multicast datagrams. Before sending out multicast
|
||||
* datagram packets however, the default outgoing interface for sending
|
||||
* multicast datagram should first be configured using
|
||||
* {@link #setOption(SocketOption, Object) setOption} and
|
||||
* {@link StandardSocketOptions#IP_MULTICAST_IF}:
|
||||
*
|
||||
* <pre>{@code
|
||||
* DatagramSocket sender = new DatagramSocket(new InetSocketAddress(0));
|
||||
* NetworkInterface outgoingIf = NetworkInterface.getByName("en0");
|
||||
* sender.setOption(StandardSocketOptions.IP_MULTICAST_IF, outgoingIf);
|
||||
*
|
||||
* // optionally configure multicast TTL; the TTL defines the scope of a
|
||||
* // multicast datagram, for example, confining it to host local (0) or
|
||||
* // link local (1) etc...
|
||||
* int ttl = ...; // a number betwen 0 and 255
|
||||
* sender.setOption(StandardSocketOptions.IP_MULTICAST_TTL, ttl);
|
||||
*
|
||||
* // send a packet to a multicast group
|
||||
* byte[] msgBytes = ...;
|
||||
* InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
|
||||
* int port = 6789;
|
||||
* InetSocketAddress dest = new InetSocketAddress(mcastaddr, port);
|
||||
* DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length, dest);
|
||||
* sender.send(hi);
|
||||
* }</pre>
|
||||
*
|
||||
* <p> An instance of {@code DatagramSocket} can also be used to receive
|
||||
* multicast datagram packets. A {@code DatagramSocket} that is created
|
||||
* with the intent of receiving multicast datagrams should be created
|
||||
* <i>unbound</i>. Before binding the socket, {@link #setReuseAddress(boolean)
|
||||
* setReuseAddress(true)} should be configured:
|
||||
*
|
||||
* <pre>{@code
|
||||
* DatagramSocket socket = new DatagramSocket(null); // unbound
|
||||
* socket.setReuseAddress(true); // set reuse address before binding
|
||||
* socket.bind(new InetSocketAddress(6789)); // bind
|
||||
*
|
||||
* // joinGroup 228.5.6.7
|
||||
* InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
|
||||
* InetSocketAddress group = new InetSocketAddress(mcastaddr, 0);
|
||||
* NetworkInterface netIf = NetworkInterface.getByName("en0");
|
||||
* socket.joinGroup(group, netIf);
|
||||
* byte[] msgBytes = new byte[1024]; // up to 1024 bytes
|
||||
* DatagramPacket packet = new DatagramPacket(msgBytes, msgBytes.length);
|
||||
* socket.receive(packet);
|
||||
* ....
|
||||
* // eventually leave group
|
||||
* socket.leaveGroup(group, netIf);
|
||||
* }</pre>
|
||||
*
|
||||
* <p><a id="PlatformDependencies"></a><b>Platform dependencies</b>
|
||||
* <p>The multicast implementation is intended to map directly to the native
|
||||
* multicasting facility. Consequently, the following items should be considered
|
||||
* when developing an application that receives IP multicast datagrams:
|
||||
* <ol>
|
||||
* <li> Contrarily to {@link DatagramChannel}, the constructors of {@code DatagramSocket}
|
||||
* do not allow to specify the {@link ProtocolFamily} of the underlying socket.
|
||||
* Consequently, the protocol family of the underlying socket may not
|
||||
* correspond to the protocol family of the multicast groups that
|
||||
* the {@code DatagramSocket} will attempt to join.
|
||||
* <br>
|
||||
* There is no guarantee that a {@code DatagramSocket} with an underlying
|
||||
* socket created in one protocol family can join and receive multicast
|
||||
* datagrams when the address of the multicast group corresponds to
|
||||
* another protocol family. For example, it is implementation specific if a
|
||||
* {@code DatagramSocket} to an IPv6 socket can join an IPv4 multicast group
|
||||
* and receive multicast datagrams sent to the group.
|
||||
* </li>
|
||||
* <li> Before joining a multicast group, the {@code DatagramSocket} should be
|
||||
* bound to the wildcard address.
|
||||
* If the socket is bound to a specific address, rather than the wildcard address
|
||||
* then it is implementation specific if multicast datagrams are received
|
||||
* by the socket.
|
||||
* </li>
|
||||
* <li> The SO_REUSEADDR option should be enabled prior to binding the socket.
|
||||
* This is required to allow multiple members of the group to bind to the same address.
|
||||
* </li>
|
||||
* </ol>
|
||||
*
|
||||
* @author Pavani Diwanji
|
||||
* @see java.net.DatagramPacket
|
||||
|
|
@ -655,14 +788,20 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
* of SO_SNDBUF then it is implementation specific if the
|
||||
* packet is sent or discarded.
|
||||
*
|
||||
* @apiNote
|
||||
* If {@code size > 0}, this method is equivalent to calling
|
||||
* {@link #setOption(SocketOption, Object)
|
||||
* setOption(StandardSocketOptions.SO_SNDBUF, size)}.
|
||||
*
|
||||
* @param size the size to which to set the send buffer
|
||||
* size. This value must be greater than 0.
|
||||
* size, in bytes. This value must be greater than 0.
|
||||
*
|
||||
* @throws SocketException if there is an error
|
||||
* in the underlying protocol, such as an UDP error.
|
||||
* @throws IllegalArgumentException if the value is 0 or is
|
||||
* negative.
|
||||
* @see #getSendBufferSize()
|
||||
* @see StandardSocketOptions#SO_SNDBUF
|
||||
* @since 1.2
|
||||
*/
|
||||
public void setSendBufferSize(int size) throws SocketException {
|
||||
|
|
@ -671,12 +810,17 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
|
||||
/**
|
||||
* Get value of the SO_SNDBUF option for this {@code DatagramSocket}, that is the
|
||||
* buffer size used by the platform for output on this {@code DatagramSocket}.
|
||||
* buffer size, in bytes, used by the platform for output on this {@code DatagramSocket}.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #getOption(SocketOption)
|
||||
* getOption(StandardSocketOptions.SO_SNDBUF)}.
|
||||
*
|
||||
* @return the value of the SO_SNDBUF option for this {@code DatagramSocket}
|
||||
* @throws SocketException if there is an error in
|
||||
* the underlying protocol, such as an UDP error.
|
||||
* @see #setSendBufferSize
|
||||
* @see StandardSocketOptions#SO_SNDBUF
|
||||
* @since 1.2
|
||||
*/
|
||||
public int getSendBufferSize() throws SocketException {
|
||||
|
|
@ -702,14 +846,20 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
* Note: It is implementation specific if a packet larger
|
||||
* than SO_RCVBUF can be received.
|
||||
*
|
||||
* @apiNote
|
||||
* If {@code size > 0}, this method is equivalent to calling
|
||||
* {@link #setOption(SocketOption, Object)
|
||||
* setOption(StandardSocketOptions.SO_RCVBUF, size)}.
|
||||
*
|
||||
* @param size the size to which to set the receive buffer
|
||||
* size. This value must be greater than 0.
|
||||
* size, in bytes. This value must be greater than 0.
|
||||
*
|
||||
* @throws SocketException if there is an error in
|
||||
* the underlying protocol, such as an UDP error.
|
||||
* @throws IllegalArgumentException if the value is 0 or is
|
||||
* negative.
|
||||
* @see #getReceiveBufferSize()
|
||||
* @see StandardSocketOptions#SO_RCVBUF
|
||||
* @since 1.2
|
||||
*/
|
||||
public void setReceiveBufferSize(int size) throws SocketException {
|
||||
|
|
@ -718,11 +868,16 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
|
||||
/**
|
||||
* Get value of the SO_RCVBUF option for this {@code DatagramSocket}, that is the
|
||||
* buffer size used by the platform for input on this {@code DatagramSocket}.
|
||||
* buffer size, in bytes, used by the platform for input on this {@code DatagramSocket}.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #getOption(SocketOption)
|
||||
* getOption(StandardSocketOptions.SO_RCVBUF)}.
|
||||
*
|
||||
* @return the value of the SO_RCVBUF option for this {@code DatagramSocket}
|
||||
* @throws SocketException if there is an error in the underlying protocol, such as an UDP error.
|
||||
* @see #setReceiveBufferSize(int)
|
||||
* @see StandardSocketOptions#SO_RCVBUF
|
||||
* @since 1.2
|
||||
*/
|
||||
public int getReceiveBufferSize() throws SocketException {
|
||||
|
|
@ -753,6 +908,10 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
* disabled after a socket is bound (See {@link #isBound()})
|
||||
* is not defined.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #setOption(SocketOption, Object)
|
||||
* setOption(StandardSocketOptions.SO_REUSEADDR, on)}.
|
||||
*
|
||||
* @param on whether to enable or disable the
|
||||
* @throws SocketException if an error occurs enabling or
|
||||
* disabling the {@code SO_REUSEADDR} socket option,
|
||||
|
|
@ -762,6 +921,7 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
* @see #bind(SocketAddress)
|
||||
* @see #isBound()
|
||||
* @see #isClosed()
|
||||
* @see StandardSocketOptions#SO_REUSEADDR
|
||||
*/
|
||||
public void setReuseAddress(boolean on) throws SocketException {
|
||||
delegate().setReuseAddress(on);
|
||||
|
|
@ -770,11 +930,16 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
/**
|
||||
* Tests if SO_REUSEADDR is enabled.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #getOption(SocketOption)
|
||||
* getOption(StandardSocketOptions.SO_REUSEADDR)}.
|
||||
*
|
||||
* @return a {@code boolean} indicating whether or not SO_REUSEADDR is enabled.
|
||||
* @throws SocketException if there is an error
|
||||
* in the underlying protocol, such as an UDP error.
|
||||
* @since 1.4
|
||||
* @see #setReuseAddress(boolean)
|
||||
* @see StandardSocketOptions#SO_REUSEADDR
|
||||
*/
|
||||
public boolean getReuseAddress() throws SocketException {
|
||||
return delegate().getReuseAddress();
|
||||
|
|
@ -787,6 +952,10 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
* started with implementation specific privileges to enable this option or
|
||||
* send broadcast datagrams.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #setOption(SocketOption, Object)
|
||||
* setOption(StandardSocketOptions.SO_BROADCAST, on)}.
|
||||
*
|
||||
* @param on
|
||||
* whether or not to have broadcast turned on.
|
||||
*
|
||||
|
|
@ -796,6 +965,7 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
*
|
||||
* @since 1.4
|
||||
* @see #getBroadcast()
|
||||
* @see StandardSocketOptions#SO_BROADCAST
|
||||
*/
|
||||
public void setBroadcast(boolean on) throws SocketException {
|
||||
delegate().setBroadcast(on);
|
||||
|
|
@ -803,11 +973,17 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
|
||||
/**
|
||||
* Tests if SO_BROADCAST is enabled.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #getOption(SocketOption)
|
||||
* getOption(StandardSocketOptions.SO_BROADCAST)}.
|
||||
*
|
||||
* @return a {@code boolean} indicating whether or not SO_BROADCAST is enabled.
|
||||
* @throws SocketException if there is an error
|
||||
* in the underlying protocol, such as an UDP error.
|
||||
* @since 1.4
|
||||
* @see #setBroadcast(boolean)
|
||||
* @see StandardSocketOptions#SO_BROADCAST
|
||||
*/
|
||||
public boolean getBroadcast() throws SocketException {
|
||||
return delegate().getBroadcast();
|
||||
|
|
@ -844,11 +1020,16 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
* for Internet Protocol v6 {@code tc} is the value that
|
||||
* would be placed into the sin6_flowinfo field of the IP header.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #setOption(SocketOption, Object)
|
||||
* setOption(StandardSocketOptions.IP_TOS, tc)}.
|
||||
*
|
||||
* @param tc an {@code int} value for the bitset.
|
||||
* @throws SocketException if there is an error setting the
|
||||
* traffic class or type-of-service
|
||||
* @since 1.4
|
||||
* @see #getTrafficClass
|
||||
* @see StandardSocketOptions#IP_TOS
|
||||
*/
|
||||
public void setTrafficClass(int tc) throws SocketException {
|
||||
delegate().setTrafficClass(tc);
|
||||
|
|
@ -864,11 +1045,16 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
* set using the {@link #setTrafficClass(int)} method on this
|
||||
* DatagramSocket.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #getOption(SocketOption)
|
||||
* getOption(StandardSocketOptions.IP_TOS)}.
|
||||
*
|
||||
* @return the traffic class or type-of-service already set
|
||||
* @throws SocketException if there is an error obtaining the
|
||||
* traffic class or type-of-service value.
|
||||
* @since 1.4
|
||||
* @see #setTrafficClass(int)
|
||||
* @see StandardSocketOptions#IP_TOS
|
||||
*/
|
||||
public int getTrafficClass() throws SocketException {
|
||||
return delegate().getTrafficClass();
|
||||
|
|
@ -1038,6 +1224,106 @@ public class DatagramSocket implements java.io.Closeable {
|
|||
return delegate().supportedOptions();
|
||||
}
|
||||
|
||||
/**
|
||||
* Joins a multicast group.
|
||||
*
|
||||
* <p> In order to join a multicast group, the caller should specify
|
||||
* the IP address of the multicast group to join, and the local
|
||||
* {@linkplain NetworkInterface network interface} to receive multicast
|
||||
* packets from.
|
||||
* <ul>
|
||||
* <li> The {@code mcastaddr} argument indicates the IP address
|
||||
* of the multicast group to join. For historical reasons this is
|
||||
* specified as a {@code SocketAddress}.
|
||||
* The default implementation only supports {@link InetSocketAddress} and
|
||||
* the {@link InetSocketAddress#getPort() port} information is ignored.
|
||||
* </li>
|
||||
* <li> The {@code netIf} argument specifies the local interface to receive
|
||||
* multicast datagram packets, or {@code null} to defer to the interface
|
||||
* set for outgoing multicast datagrams.
|
||||
* If {@code null}, and no interface has been set, the behaviour is
|
||||
* unspecified: any interface may be selected or the operation may fail
|
||||
* with a {@code SocketException}.
|
||||
* </li>
|
||||
* </ul>
|
||||
*
|
||||
* <p> It is possible to call this method several times to join
|
||||
* several different multicast groups, or join the same group
|
||||
* in several different networks. However, if the socket is already a
|
||||
* member of the group, an {@link IOException} will be thrown.
|
||||
*
|
||||
* <p>If there is a security manager, this method first
|
||||
* calls its {@code checkMulticast} method with the {@code mcastaddr}
|
||||
* argument as its argument.
|
||||
*
|
||||
* @apiNote The default interface for sending outgoing multicast datagrams
|
||||
* can be configured with {@link #setOption(SocketOption, Object)}
|
||||
* with {@link StandardSocketOptions#IP_MULTICAST_IF}.
|
||||
*
|
||||
* @param mcastaddr indicates the multicast address to join.
|
||||
* @param netIf specifies the local interface to receive multicast
|
||||
* datagram packets, or {@code null}.
|
||||
* @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 {@code null} or is a
|
||||
* SocketAddress subclass not supported by this socket
|
||||
* @see SecurityManager#checkMulticast(InetAddress)
|
||||
* @see DatagramChannel#join(InetAddress, NetworkInterface)
|
||||
* @see StandardSocketOptions#IP_MULTICAST_IF
|
||||
* @since 17
|
||||
*/
|
||||
public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf)
|
||||
throws IOException {
|
||||
delegate().joinGroup(mcastaddr, netIf);
|
||||
}
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @apiNote
|
||||
* The {@code mcastaddr} and {@code netIf} arguments should identify
|
||||
* a multicast group that was previously {@linkplain
|
||||
* #joinGroup(SocketAddress, NetworkInterface) joined} by
|
||||
* this {@code DatagramSocket}.
|
||||
* <p> It is possible to call this method several times to leave
|
||||
* multiple different multicast groups previously joined, or leave
|
||||
* the same group previously joined in multiple different networks.
|
||||
* However, if the socket is not a member of the specified group
|
||||
* in the specified network, an {@link IOException} will be
|
||||
* thrown.
|
||||
*
|
||||
* @param mcastaddr is the multicast address to leave. This should
|
||||
* contain the same IP address than that used for {@linkplain
|
||||
* #joinGroup(SocketAddress, NetworkInterface) joining}
|
||||
* the group.
|
||||
* @param netIf specifies the local interface or {@code null} to defer
|
||||
* to the interface set for outgoing multicast datagrams.
|
||||
* If {@code null}, and no interface has been set, the behaviour
|
||||
* is unspecified: any interface may be selected or the operation
|
||||
* may fail with a {@code SocketException}.
|
||||
* @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 {@code null} or is a
|
||||
* SocketAddress subclass not supported by this socket.
|
||||
* @see SecurityManager#checkMulticast(InetAddress)
|
||||
* @see #joinGroup(SocketAddress, NetworkInterface)
|
||||
* @see StandardSocketOptions#IP_MULTICAST_IF
|
||||
* @since 17
|
||||
*/
|
||||
public void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)
|
||||
throws IOException {
|
||||
delegate().leaveGroup(mcastaddr, netIf);
|
||||
}
|
||||
|
||||
// Temporary solution until JDK-8237352 is addressed
|
||||
private static final SocketAddress NO_DELEGATE = new SocketAddress() {};
|
||||
private static final boolean USE_PLAINDATAGRAMSOCKET = usePlainDatagramSocketImpl();
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 1995, 2020, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 1995, 2021, 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
|
||||
|
|
@ -44,7 +44,7 @@ import java.nio.channels.MulticastChannel;
|
|||
* with the desired port, then invoking the
|
||||
* <CODE>joinGroup(InetAddress groupAddr)</CODE>
|
||||
* method:
|
||||
* <PRE>
|
||||
* <PRE>{@code
|
||||
* // join a Multicast group and send the group salutations
|
||||
* ...
|
||||
* String msg = "Hello";
|
||||
|
|
@ -65,7 +65,7 @@ import java.nio.channels.MulticastChannel;
|
|||
* ...
|
||||
* // OK, I'm done talking - leave the group...
|
||||
* s.leaveGroup(group, netIf);
|
||||
* </PRE>
|
||||
* }</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
|
||||
|
|
@ -86,46 +86,19 @@ import java.nio.channels.MulticastChannel;
|
|||
* supports the {@link #setOption(SocketOption, Object) setOption}
|
||||
* and {@link #getOption(SocketOption) getOption} methods to set
|
||||
* and query socket options.
|
||||
* In addition to the socket options supported by
|
||||
* <a href="DatagramSocket.html#SocketOptions">{@code DatagramSocket}</a>, a
|
||||
* {@code MulticastSocket} supports the following socket options:
|
||||
* <blockquote>
|
||||
* <a id="MulticastOptions"></a>
|
||||
* <table class="striped">
|
||||
* <caption style="display:none">Socket options</caption>
|
||||
* <thead>
|
||||
* <tr>
|
||||
* <th scope="col">Option Name</th>
|
||||
* <th scope="col">Description</th>
|
||||
* </tr>
|
||||
* </thead>
|
||||
* <tbody>
|
||||
* <tr>
|
||||
* <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_IF IP_MULTICAST_IF} </th>
|
||||
* <td> The network interface for Internet Protocol (IP) multicast datagrams </td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_TTL
|
||||
* IP_MULTICAST_TTL} </th>
|
||||
* <td> The <em>time-to-live</em> for Internet Protocol (IP) multicast
|
||||
* datagrams </td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP
|
||||
* IP_MULTICAST_LOOP} </th>
|
||||
* <td> Loopback for Internet Protocol (IP) multicast datagrams </td>
|
||||
* </tr>
|
||||
* </tbody>
|
||||
* </table>
|
||||
* </blockquote>
|
||||
* <a id="MulticastOptions"></a>The set of supported socket options
|
||||
* is defined in <a href="DatagramSocket.html#SocketOptions">{@code DatagramSocket}</a>.
|
||||
* Additional (implementation specific) options may also be supported.
|
||||
*
|
||||
* @apiNote {@link DatagramChannel} implements the {@link MulticastChannel} interface
|
||||
* @apiNote {@link DatagramSocket} may be used directly for
|
||||
* sending and receiving multicast datagrams.
|
||||
* {@link DatagramChannel} implements the {@link MulticastChannel} interface
|
||||
* and provides an alternative API for sending and receiving multicast datagrams.
|
||||
* The {@link MulticastChannel} API supports both {@linkplain
|
||||
* MulticastChannel#join(InetAddress, NetworkInterface) any-source} and
|
||||
* {@linkplain MulticastChannel#join(InetAddress, NetworkInterface, InetAddress)
|
||||
* source-specific} multicast.
|
||||
* source-specific} multicast. Consider using {@link DatagramChannel} for
|
||||
* multicasting.
|
||||
*
|
||||
* @author Pavani Diwanji
|
||||
* @since 1.1
|
||||
|
|
@ -243,7 +216,7 @@ public class MulticastSocket extends DatagramSocket {
|
|||
* @param ttl the time-to-live
|
||||
* @throws IOException if an I/O exception occurs
|
||||
* while setting the default time-to-live value
|
||||
* @deprecated use the setTimeToLive method instead, which uses
|
||||
* @deprecated use the {@link #setTimeToLive(int)} method instead, which uses
|
||||
* <b>int</b> instead of <b>byte</b> as the type for ttl.
|
||||
* @see #getTTL()
|
||||
*/
|
||||
|
|
@ -262,6 +235,10 @@ public class MulticastSocket extends DatagramSocket {
|
|||
* Multicast packets sent with a TTL of {@code 0} are not transmitted
|
||||
* on the network but may be delivered locally.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #setOption(SocketOption, Object)
|
||||
* setOption(StandardSocketOptions.IP_MULTICAST_TTL, ttl)}.
|
||||
*
|
||||
* @param ttl
|
||||
* the time-to-live
|
||||
*
|
||||
|
|
@ -270,6 +247,7 @@ public class MulticastSocket extends DatagramSocket {
|
|||
* default time-to-live value
|
||||
*
|
||||
* @see #getTimeToLive()
|
||||
* @see StandardSocketOptions#IP_MULTICAST_TTL
|
||||
* @since 1.2
|
||||
*/
|
||||
public void setTimeToLive(int ttl) throws IOException {
|
||||
|
|
@ -283,8 +261,8 @@ public class MulticastSocket extends DatagramSocket {
|
|||
* @throws IOException if an I/O exception occurs
|
||||
* while getting the default time-to-live value
|
||||
* @return the default time-to-live value
|
||||
* @deprecated use the getTimeToLive method instead, which returns
|
||||
* an <b>int</b> instead of a <b>byte</b>.
|
||||
* @deprecated use the {@link #getTimeToLive()} method instead,
|
||||
* which returns an <b>int</b> instead of a <b>byte</b>.
|
||||
* @see #setTTL(byte)
|
||||
*/
|
||||
@Deprecated
|
||||
|
|
@ -295,10 +273,16 @@ public class MulticastSocket extends DatagramSocket {
|
|||
/**
|
||||
* Get the default time-to-live for multicast packets sent out on
|
||||
* the socket.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #getOption(SocketOption)
|
||||
* getOption(StandardSocketOptions.IP_MULTICAST_TTL)}.
|
||||
*
|
||||
* @throws IOException if an I/O exception occurs while
|
||||
* getting the default time-to-live value
|
||||
* @return the default time-to-live value
|
||||
* @see #setTimeToLive(int)
|
||||
* @see StandardSocketOptions#IP_MULTICAST_TTL
|
||||
* @since 1.2
|
||||
*/
|
||||
public int getTimeToLive() throws IOException {
|
||||
|
|
@ -313,6 +297,11 @@ public class MulticastSocket extends DatagramSocket {
|
|||
* calls its {@code checkMulticast} method with the
|
||||
* {@code mcastaddr} argument as its argument.
|
||||
*
|
||||
* @apiNote
|
||||
* Calling this method is equivalent to calling
|
||||
* {@link #joinGroup(SocketAddress, NetworkInterface)
|
||||
* joinGroup(new InetSocketAddress(mcastaddr, 0), null)}.
|
||||
*
|
||||
* @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,
|
||||
|
|
@ -337,6 +326,11 @@ public class MulticastSocket extends DatagramSocket {
|
|||
* calls its {@code checkMulticast} method with the
|
||||
* {@code mcastaddr} argument as its argument.
|
||||
*
|
||||
* @apiNote
|
||||
* Calling this method is equivalent to calling
|
||||
* {@link #leaveGroup(SocketAddress, NetworkInterface)
|
||||
* leaveGroup(new InetSocketAddress(mcastaddr, 0), null)}.
|
||||
*
|
||||
* @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.
|
||||
|
|
@ -353,65 +347,38 @@ public class MulticastSocket extends DatagramSocket {
|
|||
}
|
||||
|
||||
/**
|
||||
* Joins the specified multicast group at the specified interface.
|
||||
*
|
||||
* <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
|
||||
* @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)}.
|
||||
* If {@code null}, and no interface has been set, the behaviour is
|
||||
* unspecified: any interface may be selected or the operation may fail
|
||||
* with a {@code SocketException}.
|
||||
* @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 {@code null} or is a
|
||||
* SocketAddress subclass not supported by this socket
|
||||
* {@inheritDoc}
|
||||
* @throws IOException {@inheritDoc}
|
||||
* @throws SecurityException {@inheritDoc}
|
||||
* @throws IllegalArgumentException {@inheritDoc}
|
||||
* @see SecurityManager#checkMulticast(InetAddress)
|
||||
* @see DatagramChannel#join(InetAddress, NetworkInterface)
|
||||
* @since 1.4
|
||||
* @see StandardSocketOptions#IP_MULTICAST_IF
|
||||
* @see #setNetworkInterface(NetworkInterface)
|
||||
* @see #setInterface(InetAddress)
|
||||
* @since 1.4
|
||||
*/
|
||||
@Override
|
||||
public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf)
|
||||
throws IOException {
|
||||
delegate().joinGroup(mcastaddr, netIf);
|
||||
throws IOException {
|
||||
super.joinGroup(mcastaddr, netIf);
|
||||
}
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @param mcastaddr is the multicast address to leave
|
||||
* @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)}.
|
||||
* If {@code null}, and no interface has been set, the behaviour
|
||||
* is unspecified: any interface may be selected or the operation
|
||||
* may fail with a {@code SocketException}.
|
||||
* @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 {@code null} or is a
|
||||
* SocketAddress subclass not supported by this socket.
|
||||
* {@inheritDoc}
|
||||
* @apiNote {@inheritDoc}
|
||||
* @throws IOException {@inheritDoc}
|
||||
* @throws SecurityException {@inheritDoc}
|
||||
* @throws IllegalArgumentException {@inheritDoc}
|
||||
* @see SecurityManager#checkMulticast(InetAddress)
|
||||
* @since 1.4
|
||||
* @see #joinGroup(SocketAddress, NetworkInterface)
|
||||
* @since 1.4
|
||||
*/
|
||||
@Override
|
||||
public void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)
|
||||
throws IOException {
|
||||
delegate().leaveGroup(mcastaddr, netIf);
|
||||
}
|
||||
throws IOException {
|
||||
super.leaveGroup(mcastaddr, netIf);
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the multicast network interface used by methods
|
||||
|
|
@ -455,10 +422,15 @@ public class MulticastSocket extends DatagramSocket {
|
|||
* Specify the network interface for outgoing multicast datagrams
|
||||
* sent on this socket.
|
||||
*
|
||||
* @apiNote
|
||||
* This method is equivalent to calling {@link #setOption(SocketOption, Object)
|
||||
* setOption(StandardSocketOptions.IP_MULTICAST_IF, netIf)}.
|
||||
*
|
||||
* @param netIf the interface
|
||||
* @throws SocketException if there is an error in
|
||||
* the underlying protocol, such as a TCP error.
|
||||
* @see #getNetworkInterface()
|
||||
* @see StandardSocketOptions#IP_MULTICAST_IF
|
||||
* @since 1.4
|
||||
*/
|
||||
public void setNetworkInterface(NetworkInterface netIf)
|
||||
|
|
@ -467,7 +439,13 @@ public class MulticastSocket extends DatagramSocket {
|
|||
}
|
||||
|
||||
/**
|
||||
* Get the multicast network interface set.
|
||||
* Get the multicast network interface set for outgoing multicast
|
||||
* datagrams sent from this socket.
|
||||
*
|
||||
* @apiNote
|
||||
* When an interface is set, this method is equivalent
|
||||
* to calling {@link #getOption(SocketOption)
|
||||
* getOption(StandardSocketOptions.IP_MULTICAST_IF)}.
|
||||
*
|
||||
* @throws SocketException if there is an error in
|
||||
* the underlying protocol, such as a TCP error.
|
||||
|
|
@ -475,6 +453,7 @@ public class MulticastSocket extends DatagramSocket {
|
|||
* NetworkInterface is returned when there is no interface set; it has
|
||||
* a single InetAddress to represent any local address.
|
||||
* @see #setNetworkInterface(NetworkInterface)
|
||||
* @see StandardSocketOptions#IP_MULTICAST_IF
|
||||
* @since 1.4
|
||||
*/
|
||||
public NetworkInterface getNetworkInterface() throws SocketException {
|
||||
|
|
@ -564,12 +543,12 @@ public class MulticastSocket extends DatagramSocket {
|
|||
*
|
||||
*
|
||||
* @deprecated Use the following code or its equivalent instead:
|
||||
* ......
|
||||
* int ttl = mcastSocket.getTimeToLive();
|
||||
* mcastSocket.setTimeToLive(newttl);
|
||||
* <pre>{@code ......
|
||||
* int ttl = mcastSocket.getOption(StandardSocketOptions.IP_MULTICAST_TTL);
|
||||
* mcastSocket.setOption(StandardSocketOptions.IP_MULTICAST_TTL, newttl);
|
||||
* mcastSocket.send(p);
|
||||
* mcastSocket.setTimeToLive(ttl);
|
||||
* ......
|
||||
* mcastSocket.setOption(StandardSocketOptions.IP_MULTICAST_TTL, ttl);
|
||||
* ......}</pre>
|
||||
*
|
||||
* @see DatagramSocket#send
|
||||
* @see DatagramSocket#receive
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue