stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8336817: Several methods on DatagramSocket and MulticastSocket do not specify behaviour when already closed or connected

Browse Source 
Reviewed-by: dfuchs, alanb
This commit is contained in:
Jaikiran Pai 2024-08-20 12:28:56 +00:00
parent 01d03e07c7
commit 686eb233d5
2 changed files with 57 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
src/java.base/share/classes/java/net/DatagramSocket.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1995, 2023, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1995, 2024, 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
@ -395,7 +395,7 @@ public class DatagramSocket implements java.io.Closeable {
*
* @param addr The address and port to bind to.
* @throws SocketException if any error happens during the bind, or if the
* socket is already bound.
* socket is already bound or is closed.
* @throws SecurityException if a security manager exists and its
* {@code checkListen} method doesn't allow the operation.
* @throws IllegalArgumentException if addr is a SocketAddress subclass
@ -422,6 +422,11 @@ public class DatagramSocket implements java.io.Closeable {
* call to send or receive may throw a PortUnreachableException. Note,
* there is no guarantee that the exception will be thrown.
*
* <p> If this socket is already connected, then this method will attempt to
* connect to the given address. If this connect fails then the state of
* this socket is unknown - it may or may not be connected to the address
* that it was previously connected to.
*
* <p> If a security manager has been installed then it is invoked to check
* access to the remote address. Specifically, if the given {@code address}
* is a {@link InetAddress#isMulticastAddress multicast address},
@ -461,7 +466,7 @@ public class DatagramSocket implements java.io.Closeable {
* not permit access to the given remote address
*
* @throws UncheckedIOException
* may be thrown if connect fails, for example, if the
* if the port is 0 or connect fails, for example, if the
* destination address is non-routable
*
* @see #disconnect
@ -484,6 +489,11 @@ public class DatagramSocket implements java.io.Closeable {
* have not been {@linkplain #receive(DatagramPacket) received} before invoking
* this method, may be discarded.
*
* <p> If this socket is already connected, then this method will attempt to
* connect to the given address. If this connect fails then the state of
* this socket is unknown - it may or may not be connected to the address
* that it was previously connected to.
*
* @param addr The remote address.
*
* @throws SocketException
@ -643,7 +653,7 @@ public class DatagramSocket implements java.io.Closeable {
*
* @param p the {@code DatagramPacket} to be sent.
*
* @throws IOException if an I/O error occurs.
* @throws IOException if an I/O error occurs, or the socket is closed.
* @throws SecurityException if a security manager exists and its
* {@code checkMulticast} or {@code checkConnect}
* method doesn't allow the send.
@ -702,7 +712,7 @@ public class DatagramSocket implements java.io.Closeable {
*
* @param p the {@code DatagramPacket} into which to place
* the incoming data.
* @throws IOException if an I/O error occurs.
* @throws IOException if an I/O error occurs, or the socket is closed.
* @throws SocketTimeoutException if setSoTimeout was previously called
* and the timeout has expired.
* @throws PortUnreachableException may be thrown if the socket is connected
@ -770,7 +780,8 @@ public class DatagramSocket implements java.io.Closeable {
* operation to have effect.
*
* @param timeout the specified timeout in milliseconds.
* @throws SocketException if there is an error in the underlying protocol, such as an UDP error.
* @throws SocketException if there is an error in the underlying protocol,
* such as an UDP error, or the socket is closed.
* @throws IllegalArgumentException if {@code timeout} is negative
* @since 1.1
* @see #getSoTimeout()
@ -784,7 +795,8 @@ public class DatagramSocket implements java.io.Closeable {
* option is disabled (i.e., timeout of infinity).
*
* @return the setting for SO_TIMEOUT
* @throws SocketException if there is an error in the underlying protocol, such as an UDP error.
* @throws SocketException if there is an error in the underlying protocol,
* such as an UDP error, or the socket is closed.
* @since 1.1
* @see #setSoTimeout(int)
*/
@ -820,8 +832,8 @@ public class DatagramSocket implements java.io.Closeable {
* @param size the size to which to set the send buffer
* 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 SocketException if there is an error in the underlying protocol,
* such as an UDP error, or the socket is closed.
* @throws IllegalArgumentException if the value is 0 or is
* negative.
* @see #getSendBufferSize()
@ -841,8 +853,8 @@ public class DatagramSocket implements java.io.Closeable {
* 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.
* @throws SocketException if there is an error in the underlying protocol,
* such as an UDP error, or the socket is closed.
* @see #setSendBufferSize
* @see StandardSocketOptions#SO_SNDBUF
* @since 1.2
@ -878,8 +890,8 @@ public class DatagramSocket implements java.io.Closeable {
* @param size the size to which to set the receive buffer
* 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 SocketException if there is an error in the underlying protocol,
* such as an UDP error, or the socket is closed.
* @throws IllegalArgumentException if the value is 0 or is
* negative.
* @see #getReceiveBufferSize()
@ -899,7 +911,8 @@ public class DatagramSocket implements java.io.Closeable {
* 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.
* @throws SocketException if there is an error in the underlying protocol,
* such as an UDP error, or the socket is closed.
* @see #setReceiveBufferSize(int)
* @see StandardSocketOptions#SO_RCVBUF
* @since 1.2
@ -959,8 +972,8 @@ public class DatagramSocket implements java.io.Closeable {
* 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.
* @throws SocketException if there is an error in the underlying protocol,
* such as an UDP error, or the socket is closed.
* @since 1.4
* @see #setReuseAddress(boolean)
* @see StandardSocketOptions#SO_REUSEADDR
@ -983,9 +996,8 @@ public class DatagramSocket implements java.io.Closeable {
* @param on
* whether or not to have broadcast turned on.
*
* @throws SocketException
* if there is an error in the underlying protocol, such as an UDP
* error.
* @throws SocketException if there is an error in the underlying protocol,
* such as an UDP error, or the socket is closed.
*
* @since 1.4
* @see #getBroadcast()
@ -1003,8 +1015,8 @@ public class DatagramSocket implements java.io.Closeable {
* 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.
* @throws SocketException if there is an error in the underlying protocol,
* such as an UDP error, or the socket is closed.
* @since 1.4
* @see #setBroadcast(boolean)
* @see StandardSocketOptions#SO_BROADCAST
@ -1049,8 +1061,8 @@ public class DatagramSocket implements java.io.Closeable {
* 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
* @throws SocketException if there is an error setting the traffic class or type-of-service,
* or the socket is closed.
* @since 1.4
* @see #getTrafficClass
* @see StandardSocketOptions#IP_TOS
@ -1074,8 +1086,8 @@ public class DatagramSocket implements java.io.Closeable {
* 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.
* @throws SocketException if there is an error obtaining the traffic class
* or type-of-service value, or the socket is closed.
* @since 1.4
* @see #setTrafficClass(int)
* @see StandardSocketOptions#IP_TOS
@ -1092,6 +1104,9 @@ public class DatagramSocket implements java.io.Closeable {
*
* <p> If this socket has an associated channel then the channel is closed
* as well.
*
* <p> Once closed, several of the methods defined by this class will throw
* an exception if invoked on the closed socket.
*/
public void close() {
delegate().close();
@ -1299,7 +1314,7 @@ public class DatagramSocket implements java.io.Closeable {
* 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
* multicasting, or the socket is closed
* @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
@ -1343,7 +1358,7 @@ public class DatagramSocket implements java.io.Closeable {
* 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.
* is not a multicast address, or the socket is closed.
* @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

29
src/java.base/share/classes/java/net/MulticastSocket.java
View File

@ -221,7 +221,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
* while setting the default time-to-live value, or the socket is closed.
* @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()
@ -250,7 +250,7 @@ public class MulticastSocket extends DatagramSocket {
*
* @throws IOException
* if an I/O exception occurs while setting the
* default time-to-live value
* default time-to-live value, or the socket is closed.
*
* @see #getTimeToLive()
* @see StandardSocketOptions#IP_MULTICAST_TTL
@ -265,7 +265,7 @@ public class MulticastSocket extends DatagramSocket {
* the socket.
*
* @throws IOException if an I/O exception occurs
* while getting the default time-to-live value
* while getting the default time-to-live value, or the socket is closed.
* @return the default time-to-live value
* @deprecated use the {@link #getTimeToLive()} method instead,
* which returns an <b>int</b> instead of a <b>byte</b>.
@ -285,7 +285,7 @@ public class MulticastSocket extends DatagramSocket {
* getOption(StandardSocketOptions.IP_MULTICAST_TTL)}.
*
* @throws IOException if an I/O exception occurs while
* getting the default time-to-live value
* getting the default time-to-live value, or the socket is closed.
* @return the default time-to-live value
* @see #setTimeToLive(int)
* @see StandardSocketOptions#IP_MULTICAST_TTL
@ -311,7 +311,7 @@ public class MulticastSocket extends DatagramSocket {
* @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
* or the platform does not support multicasting, or the socket is closed.
* @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
@ -339,7 +339,7 @@ public class MulticastSocket extends DatagramSocket {
*
* @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.
* or when the address is not a multicast address, or the socket is closed.
* @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
@ -393,7 +393,7 @@ public class MulticastSocket extends DatagramSocket {
*
* @param inf the InetAddress
* @throws SocketException if there is an error in
* the underlying protocol, such as a TCP error.
* the underlying protocol, such as a TCP error, or the socket is closed.
* @deprecated The InetAddress may not uniquely identify
* the network interface. Use
* {@link #setNetworkInterface(NetworkInterface)} instead.
@ -413,7 +413,7 @@ public class MulticastSocket extends DatagramSocket {
* or if no interface has been set, an {@code InetAddress}
* representing any local address.
* @throws SocketException if there is an error in the
* underlying protocol, such as a TCP error.
* underlying protocol, such as a TCP error, or the socket is closed.
* @deprecated The network interface may not be uniquely identified by
* the InetAddress returned.
* Use {@link #getNetworkInterface()} instead.
@ -434,7 +434,7 @@ public class MulticastSocket extends DatagramSocket {
*
* @param netIf the interface
* @throws SocketException if there is an error in
* the underlying protocol, such as a TCP error.
* the underlying protocol, such as a TCP error, or the socket is closed.
* @see #getNetworkInterface()
* @see StandardSocketOptions#IP_MULTICAST_IF
* @since 1.4
@ -454,7 +454,7 @@ public class MulticastSocket extends DatagramSocket {
* getOption(StandardSocketOptions.IP_MULTICAST_IF)}.
*
* @throws SocketException if there is an error in
* the underlying protocol, such as a TCP error.
* the underlying protocol, such as a TCP error, or the socket is closed.
* @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.
@ -476,7 +476,8 @@ public class MulticastSocket extends DatagramSocket {
* 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
* @throws SocketException if an error occurs while setting the value, or
* the socket is closed.
* @since 1.4
* @deprecated Use {@link #setOption(SocketOption, Object)} with
* {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP}
@ -493,7 +494,8 @@ public class MulticastSocket extends DatagramSocket {
/**
* 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, or
* the socket is closed.
* @return true if the LoopbackMode has been disabled
* @since 1.4
* @deprecated Use {@link #getOption(SocketOption)} with
@ -534,8 +536,7 @@ public class MulticastSocket extends DatagramSocket {
* @param ttl optional time to live for multicast packet.
* default ttl is 1.
*
* @throws IOException is raised if an error occurs i.e
* error while setting ttl.
* @throws IOException if an I/O error occurs, or the socket is closed.
* @throws SecurityException if a security manager exists and its
* {@code checkMulticast} or {@code checkConnect}
* method doesn't allow the send.