DatagramSocketImpl (Java SE 26 & JDK 26)
Description: declaration: module: java.base, package: java.net, class: DatagramSocketImpl
Keywords: java.net.DatagramSocketImpl class

# Class DatagramSocketImpl

java.lang.Object
java.net.DatagramSocketImpl

All Implemented Interfaces:
  `SocketOptions`

public abstract class DatagramSocketImpl extends Object implements SocketOptions
Abstract datagram and multicast socket implementation base class.

Since:
  1.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected FileDescriptor`
  `fd`
  The file descriptor object.
  `protected int`
  `localPort`
  The local port number.

  ### Fields declared in interface SocketOptions

  `IP_MULTICAST_IF, IP_MULTICAST_IF2, IP_MULTICAST_LOOP, IP_TOS, SO_BINDADDR, SO_BROADCAST, SO_KEEPALIVE, SO_LINGER, SO_OOBINLINE, SO_RCVBUF, SO_REUSEADDR, SO_REUSEPORT, SO_SNDBUF, SO_TIMEOUT, TCP_NODELAY`
  Modifier and Type
  Field
  Description
  `static final int`
  `IP_MULTICAST_IF`
  See `StandardSocketOptions.IP_MULTICAST_IF` for description of this socket option.
  `static final int`
  `IP_MULTICAST_IF2`
  This option is used to both set and fetch the outgoing interface on which the multicast packets are sent.
  `static final int`
  `IP_MULTICAST_LOOP`
  See `StandardSocketOptions.IP_MULTICAST_LOOP` for description of this socket option.
  `static final int`
  `IP_TOS`
  See `StandardSocketOptions.IP_TOS` for description of this socket option.
  `static final int`
  `SO_BINDADDR`
  Fetch the local address binding of a socket.
  `static final int`
  `SO_BROADCAST`
  See `StandardSocketOptions.SO_BROADCAST` for description of this socket option.
  `static final int`
  `SO_KEEPALIVE`
  See `StandardSocketOptions.SO_KEEPALIVE` for description of this socket option.
  `static final int`
  `SO_LINGER`
  See `StandardSocketOptions.SO_LINGER` for description of this socket option.
  `static final int`
  `SO_OOBINLINE`
  When this option is set, any TCP urgent data received on the socket will be received through the socket input stream.
  `static final int`
  `SO_RCVBUF`
  See `StandardSocketOptions.SO_RCVBUF` for description of this socket option.
  `static final int`
  `SO_REUSEADDR`
  See `StandardSocketOptions.SO_REUSEADDR` for description of this socket option.
  `static final int`
  `SO_REUSEPORT`
  See `StandardSocketOptions.SO_REUSEPORT` for description of this socket option.
  `static final int`
  `SO_SNDBUF`
  See `StandardSocketOptions.SO_SNDBUF` for description of this socket option.
  `static final int`
  `SO_TIMEOUT`
  This option is used to both set and fetch a timeout value on blocking `Socket` operations: ServerSocket.accept() Socket InputStream.read() DatagramSocket.receive()
  `static final int`
  `TCP_NODELAY`
  See `StandardSocketOptions.TCP_NODELAY` for description of this socket option.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DatagramSocketImpl()`
  Constructor for subclasses to call.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected abstract void`
  `bind(int lport, InetAddress laddr)`
  Binds a datagram socket to a local port and address.
  `protected abstract void`
  `close()`
  Close the socket.
  `protected void`
  `connect(InetAddress address, int port)`
  Connects a datagram socket to a remote destination.
  `protected abstract void`
  `create()`
  Creates a datagram socket.
  `protected void`
  `disconnect()`
  Disconnects a datagram socket from its remote destination.
  `protected FileDescriptor`
  `getFileDescriptor()`
  Gets the datagram socket file descriptor.
  `protected int`
  `getLocalPort()`
  Gets the local port.
  `protected <T> T`
  `getOption(SocketOption<T> name)`
  Called to get a socket option.
  `protected abstract int`
  `getTimeToLive()`
  Retrieve the TTL (time-to-live) option.
  `protected abstract void`
  `join(InetAddress inetaddr)`
  Join the multicast group.
  `protected abstract void`
  `joinGroup(SocketAddress mcastaddr, NetworkInterface netIf)`
  Join the multicast group.
  `protected abstract void`
  `leave(InetAddress inetaddr)`
  Leave the multicast group.
  `protected abstract void`
  `leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)`
  Leave the multicast group.
  `protected abstract int`
  `peek(InetAddress i)`
  Peek at the packet to see who it is from.
  `protected abstract int`
  `peekData(DatagramPacket p)`
  Peek at the packet to see who it is from.
  `protected abstract void`
  `receive(DatagramPacket p)`
  Receive the datagram packet.
  `protected abstract void`
  `send(DatagramPacket p)`
  Sends a datagram packet.
  `protected <T> void`
  `setOption(SocketOption<T> name, T value)`
  Called to set a socket option.
  `protected abstract void`
  `setTimeToLive(int ttl)`
  Set the TTL (time-to-live) option.
  `protected Set<SocketOption<?>>`
  `supportedOptions()`
  Returns a set of SocketOptions supported by this impl and by this impl's socket (DatagramSocket or MulticastSocket)

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

  ### Methods declared in interface SocketOptions

  `getOption, setOption`
  Modifier and Type
  Method
  Description
  `Object`
  `getOption(int optID)`
  Fetch the value of an option.
  `void`
  `setOption(int optID, Object value)`
  Enable/disable the option specified by `optID`.

- ## Field Details

  - ### localPort

    protected int localPort
    The local port number.

  - ### fd

    protected FileDescriptor fd
    The file descriptor object.

- ## Constructor Details

  - ### DatagramSocketImpl

    public DatagramSocketImpl()
    Constructor for subclasses to call.

- ## Method Details

  - ### create

    protected abstract void create() throws SocketException
    Creates a datagram socket.
    Throws:
      `SocketException` - if there is an error in the underlying protocol, such as a TCP error.

  - ### bind

    protected abstract void bind(int lport, InetAddress laddr) throws SocketException
    Binds a datagram socket to a local port and address.
    Parameters:
      `lport` - the local port
      `laddr` - the local address
    Throws:
      `SocketException` - if there is an error in the underlying protocol, such as a TCP error.

  - ### send

    protected abstract void send(DatagramPacket p) throws IOException
    Sends a datagram packet. The packet contains the data and the destination address to send the packet to.
    Parameters:
      `p` - the packet to be sent.
    Throws:
      `IOException` - if an I/O exception occurs while sending the datagram packet.
      `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.

  - ### connect

    protected void connect(InetAddress address, int port) throws SocketException
    Connects a datagram socket to a remote destination. This associates the remote address with the local socket so that datagrams may only be sent to this destination and received from this destination. This may be overridden to call a native system connect.

    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.

    Implementation Requirements:
      The default implementation of this method throws `SocketException`.
    Parameters:
      `address` - the remote InetAddress to connect to
      `port` - the remote port number
    Throws:
      `SocketException` - may be thrown if the socket cannot be connected to the remote destination
    Since:
      1.4

  - ### disconnect

    protected void disconnect()
    Disconnects a datagram socket from its remote destination.
    Implementation Requirements:
      The default implementation of this method throws `UncheckedIOException`.
    Throws:
      `UncheckedIOException` - if disconnect fails or no implementation is provided
    Since:
      1.4

  - ### peek

    protected abstract int peek(InetAddress i) throws IOException
    Peek at the packet to see who it is from. Updates the specified `InetAddress` to the address which the packet came from.
    Parameters:
      `i` - an InetAddress object
    Returns:
      the port number which the packet came from.
    Throws:
      `IOException` - if an I/O exception occurs
      `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.

  - ### peekData

    protected abstract int peekData(DatagramPacket p) throws IOException
    Peek at the packet to see who it is from. The data is copied into the specified `DatagramPacket`. The data is returned, but not consumed, so that a subsequent peekData/receive operation will see the same data.
    Parameters:
      `p` - the Packet Received.
    Returns:
      the port number which the packet came from.
    Throws:
      `IOException` - if an I/O exception occurs
      `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.
    Since:
      1.4

  - ### receive

    protected abstract void receive(DatagramPacket p) throws IOException
    Receive the datagram packet.
    Parameters:
      `p` - the Packet Received.
    Throws:
      `IOException` - if an I/O exception occurs while receiving the datagram packet.
      `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.

  - ### setTimeToLive

    protected abstract void setTimeToLive(int ttl) throws IOException
    Set the TTL (time-to-live) option.
    Parameters:
      `ttl` - an `int` specifying the time-to-live value
    Throws:
      `IOException` - if an I/O exception occurs while setting the time-to-live option.
    See Also:
      - `getTimeToLive()`

  - ### getTimeToLive

    protected abstract int getTimeToLive() throws IOException
    Retrieve the TTL (time-to-live) option.
    Returns:
      an `int` representing the time-to-live value
    Throws:
      `IOException` - if an I/O exception occurs while retrieving the time-to-live option
    See Also:
      - `setTimeToLive(int)`

  - ### join

    protected abstract void join(InetAddress inetaddr) throws IOException
    Join the multicast group.
    Parameters:
      `inetaddr` - multicast address to join.
    Throws:
      `IOException` - if an I/O exception occurs while joining the multicast group.

  - ### leave

    protected abstract void leave(InetAddress inetaddr) throws IOException
    Leave the multicast group.
    Parameters:
      `inetaddr` - multicast address to leave.
    Throws:
      `IOException` - if an I/O exception occurs while leaving the multicast group.

  - ### joinGroup

    protected abstract void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf) throws IOException
    Join the multicast group.
    Parameters:
      `mcastaddr` - address to join.
      `netIf` - specifies the local interface to receive multicast datagram packets
    Throws:
      `IOException` - if an I/O exception occurs while joining the multicast group
    Since:
      1.4

  - ### leaveGroup

    protected abstract void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf) throws IOException
    Leave the multicast group.
    Parameters:
      `mcastaddr` - address to leave.
      `netIf` - specified the local interface to leave the group at
    Throws:
      `IOException` - if an I/O exception occurs while leaving the multicast group
    Since:
      1.4

  - ### close

    protected abstract void close()
    Close the socket.

  - ### getLocalPort

    protected int getLocalPort()
    Gets the local port.
    Returns:
      an `int` representing the local port value

  - ### getFileDescriptor

    protected FileDescriptor getFileDescriptor()
    Gets the datagram socket file descriptor.
    Returns:
      a `FileDescriptor` object representing the datagram socket file descriptor

  - ### setOption

    protected <T> void setOption(SocketOption<T> name, T value) throws IOException
    Called to set a socket option.
    Implementation Requirements:
      The default implementation of this method first checks that the given socket option `name` is not null, then throws `UnsupportedOperationException`. Subclasses should override this method with an appropriate implementation.
    Type Parameters:
      `T` - The type of the socket option value
    Parameters:
      `name` - The socket option
      `value` - The value of the socket option. A value of `null` may be valid for some options.
    Throws:
      `UnsupportedOperationException` - if the DatagramSocketImpl does not support the option
      `IllegalArgumentException` - if the value is not valid for the option
      `IOException` - if an I/O error occurs, or if the socket is closed
      `NullPointerException` - if name is `null`
    Since:
      9

  - ### getOption

    protected <T> T getOption(SocketOption<T> name) throws IOException
    Called to get a socket option.
    Implementation Requirements:
      The default implementation of this method first checks that the given socket option `name` is not null, then throws `UnsupportedOperationException`. Subclasses should override this method with an appropriate implementation.
    Type Parameters:
      `T` - The type of the socket option value
    Parameters:
      `name` - The socket option
    Returns:
      the socket option
    Throws:
      `UnsupportedOperationException` - if the DatagramSocketImpl does not support the option
      `IOException` - if an I/O error occurs, or if the socket is closed
      `NullPointerException` - if name is `null`
    Since:
      9

  - ### supportedOptions

    protected Set<SocketOption<?>> supportedOptions()
    Returns a set of SocketOptions supported by this impl and by this impl's socket (DatagramSocket or MulticastSocket)
    Implementation Requirements:
      The default implementation of this method returns an empty set. Subclasses should override this method with an appropriate implementation.
    Returns:
      a Set of SocketOptions
    Since:
      9