From 686eb233d59ab72e872b8dc32cb14bf74519efc5 Mon Sep 17 00:00:00 2001 From: Jaikiran Pai Date: Tue, 20 Aug 2024 12:28:56 +0000 Subject: [PATCH] 8336817: Several methods on DatagramSocket and MulticastSocket do not specify behaviour when already closed or connected Reviewed-by: dfuchs, alanb --- .../classes/java/net/DatagramSocket.java | 69 +++++++++++-------- .../classes/java/net/MulticastSocket.java | 29 ++++---- 2 files changed, 57 insertions(+), 41 deletions(-) diff --git a/src/java.base/share/classes/java/net/DatagramSocket.java b/src/java.base/share/classes/java/net/DatagramSocket.java index 9e94d1d8b62..655b00bb8b6 100644 --- a/src/java.base/share/classes/java/net/DatagramSocket.java +++ b/src/java.base/share/classes/java/net/DatagramSocket.java @@ -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. * + *

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. + * *

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. * + *

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 { * *

If this socket has an associated channel then the channel is closed * as well. + * + *

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 diff --git a/src/java.base/share/classes/java/net/MulticastSocket.java b/src/java.base/share/classes/java/net/MulticastSocket.java index 9a9d57118c0..46757a6b407 100644 --- a/src/java.base/share/classes/java/net/MulticastSocket.java +++ b/src/java.base/share/classes/java/net/MulticastSocket.java @@ -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 * int instead of byte 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 int instead of a byte. @@ -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.