< prev index next >

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

Print this page


   1 /*
   2  * Copyright (c) 1995, 2019, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.net;
  27 
  28 import java.io.IOException;

  29 import java.nio.channels.DatagramChannel;
  30 import java.security.AccessController;
  31 import java.security.PrivilegedExceptionAction;
  32 import java.util.Objects;
  33 import java.util.Set;
  34 import java.util.Collections;
  35 
  36 /**
  37  * This class represents a socket for sending and receiving datagram packets.
  38  *
  39  * <p>A datagram socket is the sending or receiving point for a packet
  40  * delivery service. Each packet sent or received on a datagram socket
  41  * is individually addressed and routed. Multiple packets sent from
  42  * one machine to another may be routed differently, and may arrive in
  43  * any order.
  44  *
  45  * <p> Where possible, a newly constructed {@code DatagramSocket} has the
  46  * {@link StandardSocketOptions#SO_BROADCAST SO_BROADCAST} socket option enabled so as
  47  * to allow the transmission of broadcast datagrams. In order to receive
  48  * broadcast packets a DatagramSocket should be bound to the wildcard address.


 439         } catch (SocketException e) {
 440             getImpl().close();
 441             throw e;
 442         }
 443         bound = true;
 444     }
 445 
 446     void checkAddress (InetAddress addr, String op) {
 447         if (addr == null) {
 448             return;
 449         }
 450         if (!(addr instanceof Inet4Address || addr instanceof Inet6Address)) {
 451             throw new IllegalArgumentException(op + ": invalid address type");
 452         }
 453     }
 454 
 455     /**
 456      * Connects the socket to a remote address for this socket. When a
 457      * socket is connected to a remote address, packets may only be
 458      * sent to or received from that address. By default a datagram
 459      * socket is not connected.

 460      *
 461      * <p>If the remote destination to which the socket is connected does not
 462      * exist, or is otherwise unreachable, and if an ICMP destination unreachable
 463      * packet has been received for that address, then a subsequent call to
 464      * send or receive may throw a PortUnreachableException. Note, there is no
 465      * guarantee that the exception will be thrown.



 466      *
 467      * <p> If a security manager has been installed then it is invoked to check
 468      * access to the remote address. Specifically, if the given {@code address}
 469      * is a {@link InetAddress#isMulticastAddress multicast address},
 470      * the security manager's {@link
 471      * java.lang.SecurityManager#checkMulticast(InetAddress)
 472      * checkMulticast} method is invoked with the given {@code address}.
 473      * Otherwise, the security manager's {@link
 474      * java.lang.SecurityManager#checkConnect(String,int) checkConnect}
 475      * and {@link java.lang.SecurityManager#checkAccept checkAccept} methods
 476      * are invoked, with the given {@code address} and {@code port}, to
 477      * verify that datagrams are permitted to be sent and received
 478      * respectively.
 479      *
 480      * <p> Care should be taken to ensure that a connected datagram socket
 481      * is not shared with untrusted code. When a socket is connected,
 482      * {@link #receive receive} and {@link #send send} <b>will not perform
 483      * any security checks</b> on incoming and outgoing packets, other than
 484      * matching the packet's and the socket's address and port. On a send
 485      * operation, if the packet's address is set and the packet's address
 486      * and the socket's address do not match, an {@code IllegalArgumentException}
 487      * will be thrown. A socket connected to a multicast address may only
 488      * be used to send packets.
 489      *
 490      * @param address the remote address for the socket
 491      *
 492      * @param port the remote port for the socket.
 493      *
 494      * @throws IllegalArgumentException
 495      *         if the address is null, or the port is out of range.
 496      *
 497      * @throws SecurityException
 498      *         if a security manager has been installed and it does
 499      *         not permit access to the given remote address
 500      *




 501      * @see #disconnect
 502      */
 503     public void connect(InetAddress address, int port) {
 504         try {
 505             connectInternal(address, port);
 506         } catch (SocketException se) {
 507             throw new Error("connect failed", se);
 508         }
 509     }
 510 
 511     /**
 512      * Connects this socket to a remote socket address (IP address + port number).
 513      *
 514      * <p> If given an {@link InetSocketAddress InetSocketAddress}, this method
 515      * behaves as if invoking {@link #connect(InetAddress,int) connect(InetAddress,int)}
 516      * with the given socket addresses IP address and port number.
 517      *
 518      * @param   addr    The remote address.
 519      *
 520      * @throws  SocketException
 521      *          if the connect fails
 522      *
 523      * @throws IllegalArgumentException
 524      *         if {@code addr} is {@code null}, or {@code addr} is a SocketAddress
 525      *         subclass not supported by this socket
 526      *
 527      * @throws SecurityException
 528      *         if a security manager has been installed and it does
 529      *         not permit access to the given remote address
 530      *
 531      * @since 1.4
 532      */
 533     public void connect(SocketAddress addr) throws SocketException {
 534         if (addr == null)
 535             throw new IllegalArgumentException("Address can't be null");
 536         if (!(addr instanceof InetSocketAddress))
 537             throw new IllegalArgumentException("Unsupported address type");
 538         InetSocketAddress epoint = (InetSocketAddress) addr;
 539         if (epoint.isUnresolved())
 540             throw new SocketException("Unresolved address");
 541         connectInternal(epoint.getAddress(), epoint.getPort());
 542     }
 543 
 544     /**
 545      * Disconnects the socket. If the socket is closed or not connected,
 546      * then this method has no effect.
 547      *








 548      * @see #connect
 549      */
 550     public void disconnect() {
 551         synchronized (this) {
 552             if (isClosed())
 553                 return;
 554             if (connectState == ST_CONNECTED) {
 555                 impl.disconnect ();
 556             }
 557             connectedAddress = null;
 558             connectedPort = -1;
 559             connectState = ST_NOT_CONNECTED;
 560             explicitFilter = false;
 561         }
 562     }
 563 
 564     /**
 565      * Returns the binding state of the socket.
 566      * <p>
 567      * If the socket was bound prior to being {@link #close closed},


   1 /*
   2  * Copyright (c) 1995, 2020, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.net;
  27 
  28 import java.io.IOException;
  29 import java.io.UncheckedIOException;
  30 import java.nio.channels.DatagramChannel;
  31 import java.security.AccessController;
  32 import java.security.PrivilegedExceptionAction;
  33 import java.util.Objects;
  34 import java.util.Set;
  35 import java.util.Collections;
  36 
  37 /**
  38  * This class represents a socket for sending and receiving datagram packets.
  39  *
  40  * <p>A datagram socket is the sending or receiving point for a packet
  41  * delivery service. Each packet sent or received on a datagram socket
  42  * is individually addressed and routed. Multiple packets sent from
  43  * one machine to another may be routed differently, and may arrive in
  44  * any order.
  45  *
  46  * <p> Where possible, a newly constructed {@code DatagramSocket} has the
  47  * {@link StandardSocketOptions#SO_BROADCAST SO_BROADCAST} socket option enabled so as
  48  * to allow the transmission of broadcast datagrams. In order to receive
  49  * broadcast packets a DatagramSocket should be bound to the wildcard address.


 440         } catch (SocketException e) {
 441             getImpl().close();
 442             throw e;
 443         }
 444         bound = true;
 445     }
 446 
 447     void checkAddress (InetAddress addr, String op) {
 448         if (addr == null) {
 449             return;
 450         }
 451         if (!(addr instanceof Inet4Address || addr instanceof Inet6Address)) {
 452             throw new IllegalArgumentException(op + ": invalid address type");
 453         }
 454     }
 455 
 456     /**
 457      * Connects the socket to a remote address for this socket. When a
 458      * socket is connected to a remote address, packets may only be
 459      * sent to or received from that address. By default a datagram
 460      * socket is not connected. If the socket is already closed,
 461      * then this method has no effect.
 462      *
 463      * <p> If this channel's socket is not bound then this method will first
 464      * cause the socket to be bound to an address that is assigned automatically,
 465      * as if invoking the {@link #bind bind} method with a parameter of
 466      * {@code null}. If the remote destination to which the socket is connected
 467      * does not exist, or is otherwise unreachable, and if an ICMP destination
 468      * unreachable packet has been received for that address, then a subsequent
 469      * call to send or receive may throw a PortUnreachableException. Note,
 470      * there is no guarantee that the exception will be thrown.
 471      *
 472      * <p> If a security manager has been installed then it is invoked to check
 473      * access to the remote address. Specifically, if the given {@code address}
 474      * is a {@link InetAddress#isMulticastAddress multicast address},
 475      * the security manager's {@link
 476      * java.lang.SecurityManager#checkMulticast(InetAddress)
 477      * checkMulticast} method is invoked with the given {@code address}.
 478      * Otherwise, the security manager's {@link
 479      * java.lang.SecurityManager#checkConnect(String,int) checkConnect}
 480      * and {@link java.lang.SecurityManager#checkAccept checkAccept} methods
 481      * are invoked, with the given {@code address} and {@code port}, to
 482      * verify that datagrams are permitted to be sent and received
 483      * respectively.
 484      *
 485      * <p> Care should be taken to ensure that a connected datagram socket
 486      * is not shared with untrusted code. When a socket is connected,
 487      * {@link #receive receive} and {@link #send send} <b>will not perform
 488      * any security checks</b> on incoming and outgoing packets, other than
 489      * matching the packet's and the socket's address and port. On a send
 490      * operation, if the packet's address is set and the packet's address
 491      * and the socket's address do not match, an {@code IllegalArgumentException}
 492      * will be thrown. A socket connected to a multicast address may only
 493      * be used to send packets.
 494      *
 495      * @param address the remote address for the socket
 496      *
 497      * @param port the remote port for the socket.
 498      *
 499      * @throws IllegalArgumentException
 500      *         if the address is null, or the port is out of range.
 501      *
 502      * @throws SecurityException
 503      *         if a security manager has been installed and it does
 504      *         not permit access to the given remote address
 505      *
 506      * @throws UncheckedIOException
 507      *         May be thrown if connect fails, for example, if the
 508      *         destination address is non-routable
 509      *
 510      * @see #disconnect
 511      */
 512     public void connect(InetAddress address, int port) {
 513         try {
 514             connectInternal(address, port);
 515         } catch (SocketException se) {
 516             throw new UncheckedIOException("connect failed", se);
 517         }
 518     }
 519 
 520     /**
 521      * Connects this socket to a remote socket address (IP address + port number).
 522      *
 523      * <p> If given an {@link InetSocketAddress InetSocketAddress}, this method
 524      * behaves as if invoking {@link #connect(InetAddress,int) connect(InetAddress,int)}
 525      * with the given socket addresses IP address and port number.
 526      *
 527      * @param   addr    The remote address.
 528      *
 529      * @throws  SocketException
 530      *          if the connect fails
 531      *
 532      * @throws IllegalArgumentException
 533      *         if {@code addr} is {@code null}, or {@code addr} is a SocketAddress
 534      *         subclass not supported by this socket
 535      *
 536      * @throws SecurityException
 537      *         if a security manager has been installed and it does
 538      *         not permit access to the given remote address
 539      *
 540      * @since 1.4
 541      */
 542     public void connect(SocketAddress addr) throws SocketException {
 543         if (addr == null)
 544             throw new IllegalArgumentException("Address can't be null");
 545         if (!(addr instanceof InetSocketAddress))
 546             throw new IllegalArgumentException("Unsupported address type");
 547         InetSocketAddress epoint = (InetSocketAddress) addr;
 548         if (epoint.isUnresolved())
 549             throw new SocketException("Unresolved address");
 550         connectInternal(epoint.getAddress(), epoint.getPort());
 551     }
 552 
 553     /**
 554      * Disconnects the socket. If the socket is closed or not connected,
 555      * then this method has no effect.
 556      *
 557      * @apiNote If this method throws an UncheckedIOException, the socket
 558      * may be left in an unspecified state. It is strongly recommended that
 559      * the socket be closed when disconnect fails.
 560      *
 561      * @throws  UncheckedIOException
 562      *          May be thrown if disconnect fails to dissolve the
 563      *          association and restore the socket to a consistent state.
 564      *
 565      * @see #connect
 566      */
 567     public void disconnect() {
 568         synchronized (this) {
 569             if (isClosed())
 570                 return;
 571             if (connectState == ST_CONNECTED) {
 572                 impl.disconnect ();
 573             }
 574             connectedAddress = null;
 575             connectedPort = -1;
 576             connectState = ST_NOT_CONNECTED;
 577             explicitFilter = false;
 578         }
 579     }
 580 
 581     /**
 582      * Returns the binding state of the socket.
 583      * <p>
 584      * If the socket was bound prior to being {@link #close closed},


< prev index next >