src/java.base/share/classes/java/net/DatagramSocket.java

*** 1,7 ****
  /*
!  * Copyright (c) 1995, 2019, 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
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
--- 1,7 ----
  /*
!  * Copyright (c) 1995, 2020, 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
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
*** 24,33 ****
--- 24,34 ----
   */
  
  package java.net;
  
  import java.io.IOException;
+ import java.io.UncheckedIOException;
  import java.nio.channels.DatagramChannel;
  import java.security.AccessController;
  import java.security.PrivilegedExceptionAction;
  import java.util.Objects;
  import java.util.Set;
*** 454,470 ****
  
      /**
       * Connects the socket to a remote address for this socket. When a
       * socket is connected to a remote address, packets may only be
       * sent to or received from that address. By default a datagram
!      * socket is not connected.
       *
!      * <p>If the remote destination to which the socket is connected does not
!      * exist, or is otherwise unreachable, and if an ICMP destination unreachable
!      * packet has been received for that address, then a subsequent call to
!      * send or receive may throw a PortUnreachableException. Note, there is no
!      * guarantee that the exception will be thrown.
       *
       * <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},
       * the security manager's {@link
--- 455,475 ----
  
      /**
       * Connects the socket to a remote address for this socket. When a
       * socket is connected to a remote address, packets may only be
       * sent to or received from that address. By default a datagram
!      * socket is not connected. If the socket is already closed,
!      * then this method has no effect.
       *
!      * <p> If this socket is not bound then this method will first cause the
!      * socket to be bound to an address that is assigned automatically,
!      * as if invoking the {@link #bind bind} method with a parameter of
!      * {@code null}. If the remote destination to which the socket is connected
!      * does not exist, or is otherwise unreachable, and if an ICMP destination
!      * unreachable packet has been received for that address, then a subsequent
!      * call to send or receive may throw a PortUnreachableException. Note,
!      * there is no guarantee that the exception will be thrown.
       *
       * <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},
       * the security manager's {@link
*** 496,512 ****
       *
       * @throws SecurityException
       *         if a security manager has been installed and it does
       *         not permit access to the given remote address
       *
       * @see #disconnect
       */
      public void connect(InetAddress address, int port) {
          try {
              connectInternal(address, port);
          } catch (SocketException se) {
!             throw new Error("connect failed", se);
          }
      }
  
      /**
       * Connects this socket to a remote socket address (IP address + port number).
--- 501,522 ----
       *
       * @throws SecurityException
       *         if a security manager has been installed and it does
       *         not permit access to the given remote address
       *
+      * @throws UncheckedIOException
+      *         may be thrown if connect fails, for example, if the
+      *         destination address is non-routable
+      *
       * @see #disconnect
+      * @since 1.2
       */
      public void connect(InetAddress address, int port) {
          try {
              connectInternal(address, port);
          } catch (SocketException se) {
!             throw new UncheckedIOException("connect failed", se);
          }
      }
  
      /**
       * Connects this socket to a remote socket address (IP address + port number).
*** 543,553 ****
--- 553,573 ----
  
      /**
       * Disconnects the socket. If the socket is closed or not connected,
       * then this method has no effect.
       *
+      * @apiNote If this method throws an UncheckedIOException, the socket
+      *          may be left in an unspecified state. It is strongly
+      *          recommended that the socket be closed when disconnect
+      *          fails.
+      *
+      * @throws  UncheckedIOException
+      *          may be thrown if disconnect fails to dissolve the
+      *          association and restore the socket to a consistent state.
+      *
       * @see #connect
+      * @since 1.2
       */
      public void disconnect() {
          synchronized (this) {
              if (isClosed())
                  return;