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

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
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. * 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
@ -395,7 +395,7 @@ public class DatagramSocket implements java.io.Closeable {
* *
* @param addr The address and port to bind to. * @param addr The address and port to bind to.
* @throws SocketException if any error happens during the bind, or if the * @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 * @throws SecurityException if a security manager exists and its
* {@code checkListen} method doesn't allow the operation. * {@code checkListen} method doesn't allow the operation.
* @throws IllegalArgumentException if addr is a SocketAddress subclass * @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, * call to send or receive may throw a PortUnreachableException. Note,
* there is no guarantee that the exception will be thrown. * 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 * <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} * access to the remote address. Specifically, if the given {@code address}
* is a {@link InetAddress#isMulticastAddress multicast 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 * not permit access to the given remote address
* *
* @throws UncheckedIOException * @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 * destination address is non-routable
* *
* @see #disconnect * @see #disconnect
@ -484,6 +489,11 @@ public class DatagramSocket implements java.io.Closeable {
* have not been {@linkplain #receive(DatagramPacket) received} before invoking * have not been {@linkplain #receive(DatagramPacket) received} before invoking
* this method, may be discarded. * 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. * @param addr The remote address.
* *
* @throws SocketException * @throws SocketException
@ -643,7 +653,7 @@ public class DatagramSocket implements java.io.Closeable {
* *
* @param p the {@code DatagramPacket} to be sent. * @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 * @throws SecurityException if a security manager exists and its
* {@code checkMulticast} or {@code checkConnect} * {@code checkMulticast} or {@code checkConnect}
* method doesn't allow the send. * 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 * @param p the {@code DatagramPacket} into which to place
* the incoming data. * 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 * @throws SocketTimeoutException if setSoTimeout was previously called
* and the timeout has expired. * and the timeout has expired.
* @throws PortUnreachableException may be thrown if the socket is connected * @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. * operation to have effect.
* *
* @param timeout the specified timeout in milliseconds. * @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 * @throws IllegalArgumentException if {@code timeout} is negative
* @since 1.1 * @since 1.1
* @see #getSoTimeout() * @see #getSoTimeout()
@ -784,7 +795,8 @@ public class DatagramSocket implements java.io.Closeable {
* option is disabled (i.e., timeout of infinity). * option is disabled (i.e., timeout of infinity).
* *
* @return the setting for SO_TIMEOUT * @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 * @since 1.1
* @see #setSoTimeout(int) * @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 * @param size the size to which to set the send buffer
* size, in bytes. This value must be greater than 0. * size, in bytes. This value must be greater than 0.
* *
* @throws SocketException if there is an error * @throws SocketException if there is an error in the underlying protocol,
* in the underlying protocol, such as an UDP error. * such as an UDP error, or the socket is closed.
* @throws IllegalArgumentException if the value is 0 or is * @throws IllegalArgumentException if the value is 0 or is
* negative. * negative.
* @see #getSendBufferSize() * @see #getSendBufferSize()
@ -841,8 +853,8 @@ public class DatagramSocket implements java.io.Closeable {
* getOption(StandardSocketOptions.SO_SNDBUF)}. * getOption(StandardSocketOptions.SO_SNDBUF)}.
* *
* @return the value of the SO_SNDBUF option for this {@code DatagramSocket} * @return the value of the SO_SNDBUF option for this {@code DatagramSocket}
* @throws SocketException if there is an error in * @throws SocketException if there is an error in the underlying protocol,
* the underlying protocol, such as an UDP error. * such as an UDP error, or the socket is closed.
* @see #setSendBufferSize * @see #setSendBufferSize
* @see StandardSocketOptions#SO_SNDBUF * @see StandardSocketOptions#SO_SNDBUF
* @since 1.2 * @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 * @param size the size to which to set the receive buffer
* size, in bytes. 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 * @throws SocketException if there is an error in the underlying protocol,
* the underlying protocol, such as an UDP error. * such as an UDP error, or the socket is closed.
* @throws IllegalArgumentException if the value is 0 or is * @throws IllegalArgumentException if the value is 0 or is
* negative. * negative.
* @see #getReceiveBufferSize() * @see #getReceiveBufferSize()
@ -899,7 +911,8 @@ public class DatagramSocket implements java.io.Closeable {
* getOption(StandardSocketOptions.SO_RCVBUF)}. * getOption(StandardSocketOptions.SO_RCVBUF)}.
* *
* @return the value of the SO_RCVBUF option for this {@code DatagramSocket} * @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 #setReceiveBufferSize(int)
* @see StandardSocketOptions#SO_RCVBUF * @see StandardSocketOptions#SO_RCVBUF
* @since 1.2 * @since 1.2
@ -959,8 +972,8 @@ public class DatagramSocket implements java.io.Closeable {
* getOption(StandardSocketOptions.SO_REUSEADDR)}. * getOption(StandardSocketOptions.SO_REUSEADDR)}.
* *
* @return a {@code boolean} indicating whether or not SO_REUSEADDR is enabled. * @return a {@code boolean} indicating whether or not SO_REUSEADDR is enabled.
* @throws SocketException if there is an error * @throws SocketException if there is an error in the underlying protocol,
* in the underlying protocol, such as an UDP error. * such as an UDP error, or the socket is closed.
* @since 1.4 * @since 1.4
* @see #setReuseAddress(boolean) * @see #setReuseAddress(boolean)
* @see StandardSocketOptions#SO_REUSEADDR * @see StandardSocketOptions#SO_REUSEADDR
@ -983,9 +996,8 @@ public class DatagramSocket implements java.io.Closeable {
* @param on * @param on
* whether or not to have broadcast turned on. * whether or not to have broadcast turned on.
* *
* @throws SocketException * @throws SocketException if there is an error in the underlying protocol,
* if there is an error in the underlying protocol, such as an UDP * such as an UDP error, or the socket is closed.
* error.
* *
* @since 1.4 * @since 1.4
* @see #getBroadcast() * @see #getBroadcast()
@ -1003,8 +1015,8 @@ public class DatagramSocket implements java.io.Closeable {
* getOption(StandardSocketOptions.SO_BROADCAST)}. * getOption(StandardSocketOptions.SO_BROADCAST)}.
* *
* @return a {@code boolean} indicating whether or not SO_BROADCAST is enabled. * @return a {@code boolean} indicating whether or not SO_BROADCAST is enabled.
* @throws SocketException if there is an error * @throws SocketException if there is an error in the underlying protocol,
* in the underlying protocol, such as an UDP error. * such as an UDP error, or the socket is closed.
* @since 1.4 * @since 1.4
* @see #setBroadcast(boolean) * @see #setBroadcast(boolean)
* @see StandardSocketOptions#SO_BROADCAST * @see StandardSocketOptions#SO_BROADCAST
@ -1049,8 +1061,8 @@ public class DatagramSocket implements java.io.Closeable {
* setOption(StandardSocketOptions.IP_TOS, tc)}. * setOption(StandardSocketOptions.IP_TOS, tc)}.
* *
* @param tc an {@code int} value for the bitset. * @param tc an {@code int} value for the bitset.
* @throws SocketException if there is an error setting the * @throws SocketException if there is an error setting the traffic class or type-of-service,
* traffic class or type-of-service * or the socket is closed.
* @since 1.4 * @since 1.4
* @see #getTrafficClass * @see #getTrafficClass
* @see StandardSocketOptions#IP_TOS * @see StandardSocketOptions#IP_TOS
@ -1074,8 +1086,8 @@ public class DatagramSocket implements java.io.Closeable {
* getOption(StandardSocketOptions.IP_TOS)}. * getOption(StandardSocketOptions.IP_TOS)}.
* *
* @return the traffic class or type-of-service already set * @return the traffic class or type-of-service already set
* @throws SocketException if there is an error obtaining the * @throws SocketException if there is an error obtaining the traffic class
* traffic class or type-of-service value. * or type-of-service value, or the socket is closed.
* @since 1.4 * @since 1.4
* @see #setTrafficClass(int) * @see #setTrafficClass(int)
* @see StandardSocketOptions#IP_TOS * @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 * <p> If this socket has an associated channel then the channel is closed
* as well. * 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() { public void close() {
delegate().close(); delegate().close();
@ -1299,7 +1314,7 @@ public class DatagramSocket implements java.io.Closeable {
* datagram packets, or {@code null}. * datagram packets, or {@code null}.
* @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, or the socket is closed
* @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 {@code null} or is a * @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 * is unspecified: any interface may be selected or the operation
* may fail with a {@code SocketException}. * may fail with a {@code SocketException}.
* @throws IOException if there is an error leaving or when the address * @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 * @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 {@code null} or is a * @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 * @param ttl the time-to-live
* @throws IOException if an I/O exception occurs * @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 * @deprecated use the {@link #setTimeToLive(int)} method instead, which uses
* <b>int</b> instead of <b>byte</b> as the type for ttl. * <b>int</b> instead of <b>byte</b> as the type for ttl.
* @see #getTTL() * @see #getTTL()
@ -250,7 +250,7 @@ public class MulticastSocket extends DatagramSocket {
* *
* @throws IOException * @throws IOException
* if an I/O exception occurs while setting the * 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 #getTimeToLive()
* @see StandardSocketOptions#IP_MULTICAST_TTL * @see StandardSocketOptions#IP_MULTICAST_TTL
@ -265,7 +265,7 @@ public class MulticastSocket extends DatagramSocket {
* the socket. * the socket.
* *
* @throws IOException if an I/O exception occurs * @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 * @return the default time-to-live value
* @deprecated use the {@link #getTimeToLive()} method instead, * @deprecated use the {@link #getTimeToLive()} method instead,
* which returns an <b>int</b> instead of a <b>byte</b>. * 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)}. * getOption(StandardSocketOptions.IP_MULTICAST_TTL)}.
* *
* @throws IOException if an I/O exception occurs while * @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 * @return the default time-to-live value
* @see #setTimeToLive(int) * @see #setTimeToLive(int)
* @see StandardSocketOptions#IP_MULTICAST_TTL * @see StandardSocketOptions#IP_MULTICAST_TTL
@ -311,7 +311,7 @@ public class MulticastSocket extends DatagramSocket {
* @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 is not a multicast address, * 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 * @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 * @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 * @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, or the socket is closed.
* @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 * @deprecated This method does not accept the network interface on which
@ -393,7 +393,7 @@ public class MulticastSocket extends DatagramSocket {
* *
* @param inf the InetAddress * @param inf the InetAddress
* @throws SocketException if there is an error in * @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 * @deprecated The InetAddress may not uniquely identify
* the network interface. Use * the network interface. Use
* {@link #setNetworkInterface(NetworkInterface)} instead. * {@link #setNetworkInterface(NetworkInterface)} instead.
@ -413,7 +413,7 @@ public class MulticastSocket extends DatagramSocket {
* or if no interface has been set, an {@code InetAddress} * or if no interface has been set, an {@code InetAddress}
* representing any local address. * representing any local address.
* @throws SocketException if there is an error in the * @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 * @deprecated The network interface may not be uniquely identified by
* the InetAddress returned. * the InetAddress returned.
* Use {@link #getNetworkInterface()} instead. * Use {@link #getNetworkInterface()} instead.
@ -434,7 +434,7 @@ public class MulticastSocket extends DatagramSocket {
* *
* @param netIf the interface * @param netIf the interface
* @throws SocketException if there is an error in * @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 #getNetworkInterface()
* @see StandardSocketOptions#IP_MULTICAST_IF * @see StandardSocketOptions#IP_MULTICAST_IF
* @since 1.4 * @since 1.4
@ -454,7 +454,7 @@ public class MulticastSocket extends DatagramSocket {
* getOption(StandardSocketOptions.IP_MULTICAST_IF)}. * getOption(StandardSocketOptions.IP_MULTICAST_IF)}.
* *
* @throws SocketException if there is an error in * @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 * @return The multicast {@code NetworkInterface} currently set. A placeholder
* NetworkInterface is returned when there is no interface set; it has * NetworkInterface is returned when there is no interface set; it has
* a single InetAddress to represent any local address. * 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 * 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, or
* the socket is closed.
* @since 1.4 * @since 1.4
* @deprecated Use {@link #setOption(SocketOption, Object)} with * @deprecated Use {@link #setOption(SocketOption, Object)} with
* {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP} * {@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. * 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 * @return true if the LoopbackMode has been disabled
* @since 1.4 * @since 1.4
* @deprecated Use {@link #getOption(SocketOption)} with * @deprecated Use {@link #getOption(SocketOption)} with
@ -534,8 +536,7 @@ public class MulticastSocket extends DatagramSocket {
* @param ttl optional time to live for multicast packet. * @param ttl optional time to live for multicast packet.
* default ttl is 1. * default ttl is 1.
* *
* @throws IOException is raised if an error occurs i.e * @throws IOException if an I/O error occurs, or the socket is closed.
* error while setting ttl.
* @throws SecurityException if a security manager exists and its * @throws SecurityException if a security manager exists and its
* {@code checkMulticast} or {@code checkConnect} * {@code checkMulticast} or {@code checkConnect}
* method doesn't allow the send. * method doesn't allow the send.