jdk-sandbox: comparison src/java.base/share/classes/java/net/DatagramSocket.java

equal deleted inserted replaced

-:13588c901957
+:9cf78a70fa4f
 * <p>If there is a security manager,
 * its {@code checkListen} method is first called
 * with 0 as its argument to ensure the operation is allowed.
 * This could result in a SecurityException.
 *
-* @exception  SocketException  if the socket could not be opened,
+* @throws     SocketException  if the socket could not be opened,
 *               or the socket could not bind to the specified local port.
-* @exception  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.
 *
 * @see SecurityManager#checkListen
 */
 public DatagramSocket() throws SocketException {
 * This could result in a SecurityException.
 *
 * @param bindaddr local socket address to bind, or {@code null}
 *                 for an unbound socket.
 *
-* @exception  SocketException  if the socket could not be opened,
+* @throws     SocketException  if the socket could not be opened,
 *               or the socket could not bind to the specified local port.
-* @exception  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.
 *
 * @see SecurityManager#checkListen
 * @since   1.4
 */
 * with the {@code port} argument
 * as its argument to ensure the operation is allowed.
 * This could result in a SecurityException.
 *
 * @param      port port to use.
-* @exception  SocketException  if the socket could not be opened,
+* @throws     SocketException  if the socket could not be opened,
 *               or the socket could not bind to the specified local port.
-* @exception  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.
 *
 * @see SecurityManager#checkListen
 */
 public DatagramSocket(int port) throws SocketException {
 * This could result in a SecurityException.
 *
 * @param port local port to use
 * @param laddr local address to bind
 *
-* @exception  SocketException  if the socket could not be opened,
+* @throws     SocketException  if the socket could not be opened,
 *               or the socket could not bind to the specified local port.
-* @exception  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.
 *
 * @see SecurityManager#checkListen
 * @since   1.1
 */
 * and {@link java.lang.SecurityManager#checkAccept checkAccept} methods
 * are invoked, with the given {@code address} and {@code port}, to
 * verify that datagrams are permitted to be sent and received
 * respectively.
 *
-* <p> When a socket is connected, {@link #receive receive} and
+* <p> Care should be taken to ensure that a connected datagram socket
-* {@link #send send} <b>will not perform any security checks</b>
+* is not shared with untrusted code. When a socket is connected,
-* on incoming and outgoing packets, other than matching the packet's
+* {@link #receive receive} and {@link #send send} <b>will not perform
-* and the socket's address and port. On a send operation, if the
+* any security checks</b> on incoming and outgoing packets, other than
-* packet's address is set and the packet's address and the socket's
+* matching the packet's and the socket's address and port. On a send
-* address do not match, an {@code IllegalArgumentException} will be
+* operation, if the packet's address is set and the packet's address
-* thrown. A socket connected to a multicast address may only be used
+* and the socket's address do not match, an {@code IllegalArgumentException}
-* to send packets.
+* will be thrown. A socket connected to a multicast address may only
+* be used to send packets.
 *
 * @param address the remote address for the socket
 *
 * @param port the remote port for the socket.
 *
 * {@code p.getPort()}. Each call to a security manager method
 * could result in a SecurityException if the operation is not allowed.
 *
 * @param      p   the {@code DatagramPacket} to be sent.
 *
-* @exception  IOException  if an I/O error occurs.
+* @throws     IOException  if an I/O error occurs.
-* @exception  SecurityException  if a security manager exists and its
+* @throws     SecurityException  if a security manager exists and its
 *             {@code checkMulticast} or {@code checkConnect}
 *             method doesn't allow the send.
-* @exception  PortUnreachableException may be thrown if the socket is connected
+* @throws     PortUnreachableException may be thrown if the socket is connected
 *             to a currently unreachable destination. Note, there is no
 *             guarantee that the exception will be thrown.
-* @exception  java.nio.channels.IllegalBlockingModeException
+* @throws     java.nio.channels.IllegalBlockingModeException
 *             if this socket has an associated channel,
 *             and the channel is in non-blocking mode.
-* @exception  IllegalArgumentException if the socket is connected,
+* @throws     IllegalArgumentException if the socket is connected,
 *             and connected address and packet address differ.
 *
 * @see        java.net.DatagramPacket
 * @see        SecurityManager#checkMulticast(InetAddress)
 * @see        SecurityManager#checkConnect
 * This method blocks until a datagram is received. The
 * {@code length} field of the datagram packet object contains
 * the length of the received message. If the message is longer than
 * the packet's length, the message is truncated.
 * <p>
-* If there is a security manager, a packet cannot be received if the
+* If there is a security manager, and the socket is not currently
-* security manager's {@code checkAccept} method
+* connected to a remote address, a packet cannot be received if the
-* does not allow it.
+* security manager's {@code checkAccept} method does not allow it.
+* Datagrams that are not permitted by the security manager are silently
+* discarded.
 *
 * @param      p   the {@code DatagramPacket} into which to place
 *                 the incoming data.
-* @exception  IOException  if an I/O error occurs.
+* @throws     IOException  if an I/O error occurs.
-* @exception  SocketTimeoutException  if setSoTimeout was previously called
+* @throws     SocketTimeoutException  if setSoTimeout was previously called
 *                 and the timeout has expired.
-* @exception  PortUnreachableException may be thrown if the socket is connected
+* @throws     PortUnreachableException may be thrown if the socket is connected
 *             to a currently unreachable destination. Note, there is no guarantee that the
 *             exception will be thrown.
-* @exception  java.nio.channels.IllegalBlockingModeException
+* @throws     java.nio.channels.IllegalBlockingModeException
 *             if this socket has an associated channel,
 *             and the channel is in non-blocking mode.
 * @see        java.net.DatagramPacket
 * @see        java.net.DatagramSocket
 * @revised 1.4
 *  timeout must be {@code > 0}.
 *  A timeout of zero is interpreted as an infinite timeout.
 *
 * @param timeout the specified timeout in milliseconds.
 * @throws SocketException if there is an error in the underlying protocol, such as an UDP error.
+* @throws IllegalArgumentException if {@code timeout} is negative
 * @since   1.1
 * @see #getSoTimeout()
 */
 public synchronized void setSoTimeout(int timeout) throws SocketException {
 if (isClosed())
 throw new SocketException("Socket is closed");
+if (timeout < 0)
+throw new IllegalArgumentException("timeout < 0");
 getImpl().setOption(SocketOptions.SO_TIMEOUT, timeout);
 }
 /**
 * Retrieve setting for SO_TIMEOUT.  0 returns implies that the
 * packet is sent or discarded.
 *
 * @param size the size to which to set the send buffer
 * size. This value must be greater than 0.
 *
-* @exception SocketException if there is an error
+* @throws    SocketException if there is an error
 * in the underlying protocol, such as an UDP error.
-* @exception IllegalArgumentException if the value is 0 or is
+* @throws    IllegalArgumentException if the value is 0 or is
 * negative.
 * @see #getSendBufferSize()
 */
 public synchronized void setSendBufferSize(int size)
 throws SocketException{
 /**
 * 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}.
 *
 * @return the value of the SO_SNDBUF option for this {@code DatagramSocket}
-* @exception SocketException if there is an error in
+* @throws    SocketException if there is an error in
 * the underlying protocol, such as an UDP error.
 * @see #setSendBufferSize
 */
 public synchronized int getSendBufferSize() throws SocketException {
 if (isClosed())
 * than SO_RCVBUF can be received.
 *
 * @param size the size to which to set the receive buffer
 * size. This value must be greater than 0.
 *
-* @exception SocketException if there is an error in
+* @throws    SocketException if there is an error in
 * the underlying protocol, such as an UDP error.
-* @exception IllegalArgumentException if the value is 0 or is
+* @throws    IllegalArgumentException if the value is 0 or is
 * negative.
 * @see #getReceiveBufferSize()
 */
 public synchronized void setReceiveBufferSize(int size)
 throws SocketException{
 /**
 * 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}.
 *
 * @return the value of the SO_RCVBUF option for this {@code DatagramSocket}
-* @exception 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.
 * @see #setReceiveBufferSize(int)
 */
 public synchronized int getReceiveBufferSize()
 throws SocketException{
 if (isClosed())
 * The behaviour when {@code SO_REUSEADDR} is enabled or
 * disabled after a socket is bound (See {@link #isBound()})
 * is not defined.
 *
 * @param on  whether to enable or disable the
-* @exception SocketException if an error occurs enabling or
+* @throws    SocketException if an error occurs enabling or
 *            disabling the {@code SO_REUSEADDR} socket option,
 *            or the socket is closed.
 * @since 1.4
 * @see #getReuseAddress()
 * @see #bind(SocketAddress)
 /**
 * Tests if SO_REUSEADDR is enabled.
 *
 * @return a {@code boolean} indicating whether or not SO_REUSEADDR is enabled.
-* @exception SocketException if there is an error
+* @throws    SocketException if there is an error
 * in the underlying protocol, such as an UDP error.
 * @since   1.4
 * @see #setReuseAddress(boolean)
 */
 public synchronized boolean getReuseAddress() throws SocketException {
 }
 /**
 * Tests if SO_BROADCAST is enabled.
 * @return a {@code boolean} indicating whether or not SO_BROADCAST is enabled.
-* @exception SocketException if there is an error
+* @throws    SocketException if there is an error
 * in the underlying protocol, such as an UDP error.
 * @since 1.4
 * @see #setBroadcast(boolean)
 */
 public synchronized boolean getBroadcast() throws SocketException {
 * the security manager's {@code checkSetFactory} method
 * to ensure the operation is allowed.
 * This could result in a SecurityException.
 *
 * @param      fac   the desired factory.
-* @exception  IOException  if an I/O error occurs when setting the
+* @throws     IOException  if an I/O error occurs when setting the
 *              datagram socket factory.
-* @exception  SocketException  if the factory is already defined.
+* @throws     SocketException  if the factory is already defined.
-* @exception  SecurityException  if a security manager exists and its
+* @throws     SecurityException  if a security manager exists and its
 *             {@code checkSetFactory} method doesn't allow the operation.
 * @see       java.net.DatagramSocketImplFactory#createDatagramSocketImpl()
 * @see       SecurityManager#checkSetFactory
 * @since 1.3
 */

branch	datagramsocketimpl-branch
changeset 58678	9cf78a70fa4f
parent 55081	dd321e3596c0
child 58679	9c3209ff7550