java/15 : java.base/java/net/DatagramSocketImpl.java

DatagramSocketImpl

https://openjdk.java.net/

GPLv2 + Classpath Exception

/*
 * Copyright (c) 1996, 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
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.net;

import java.io.FileDescriptor;
import java.io.IOException;
import java.util.Objects;
import java.util.Set;

Abstract datagram and multicast socket implementation base class.
Author: Pavani Diwanji
Implementation Note: Sockets created with the DatagramSocket and 
MulticastSocket public constructors historically delegated all socket operations to a DatagramSocketImpl implementation named "PlainDatagramSocketImpl". DatagramSocket and MulticastSocket have since been changed to a new implementation based on DatagramChannel. The JDK continues to ship with the older implementation to allow code to run that depends on unspecified behavior that differs between the old and new implementations. The old implementation will be used if the Java virtual machine is started with the system property jdk.net.usePlainDatagramSocketImpl set to use the old implementation. It may also be set in the JDK's network configuration file, located in 
${java.home}/conf/net.properties. The value of the property is the string representation of a boolean. If set without a value then it defaults to 
true, hence running with -Djdk.net.usePlainDatagramSocketImpl or -Djdk.net.usePlainDatagramSocketImpl=true will configure the Java virtual machine to use the old implementation. The property and old implementation will be removed in a future version.
Since:  1.1/**
 * Abstract datagram and multicast socket implementation base class.
 *
 * @implNote Sockets created with the {@code DatagramSocket} and {@code
 * MulticastSocket} public constructors historically delegated all socket
 * operations to a {@code DatagramSocketImpl} implementation named
 * "PlainDatagramSocketImpl". {@code DatagramSocket} and {@code MulticastSocket}
 * have since been changed to a new implementation based on {@code DatagramChannel}.
 * The JDK continues to ship with the older implementation to allow code to run
 * that depends on unspecified behavior that differs between the old and new
 * implementations. The old implementation will be used if the Java virtual
 * machine is started with the system property {@systemProperty
 * jdk.net.usePlainDatagramSocketImpl} set to use the old implementation. It may
 * also be set in the JDK's network configuration file, located in {@code
 * ${java.home}/conf/net.properties}. The value of the property is the string
 * representation of a boolean. If set without a value then it defaults to {@code
 * true}, hence running with {@code -Djdk.net.usePlainDatagramSocketImpl} or
 * {@code -Djdk.net.usePlainDatagramSocketImpl=true} will configure the Java
 * virtual machine to use the old implementation. The property and old
 * implementation will be removed in a future version.
 *
 * @author Pavani Diwanji
 * @since  1.1
 */

public abstract class DatagramSocketImpl implements SocketOptions {

    The local port number.
/**
     * The local port number.
     */
    protected int localPort;

    The file descriptor object.
/**
     * The file descriptor object.
     */
    protected FileDescriptor fd;

    int dataAvailable() {
        // default impl returns zero, which disables the calling
        // functionality
        return 0;
    }

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

    Binds a datagram socket to a local port and address.
Params: lport – the local port
laddr – the local address
Throws: SocketException – if there is an error in the
           underlying protocol, such as a TCP error./**
     * Binds a datagram socket to a local port and address.
     * @param     lport the local port
     * @param     laddr the local address
     * @throws    SocketException if there is an error in the
     *            underlying protocol, such as a TCP error.
     */
    protected abstract void bind(int lport, InetAddress laddr) throws SocketException;

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

    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.
Params: 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/**
     * 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.
     *
     * <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.
     * @param   address the remote InetAddress to connect to
     * @param   port the remote port number
     * @throws  SocketException may be thrown if the socket cannot be
     *          connected to the remote destination
     * @since   1.4
     */
    protected void connect(InetAddress address, int port) throws SocketException {}

    Disconnects a datagram socket from its remote destination.
Since: 1.4/**
     * Disconnects a datagram socket from its remote destination.
     * @since 1.4
     */
    protected void disconnect() {}

    Peek at the packet to see who it is from. Updates the specified InetAddress to the address which the packet came from. 
Params: i – an InetAddress object
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.
Returns:    the port number which the packet came from./**
     * Peek at the packet to see who it is from. Updates the specified {@code InetAddress}
     * to the address which the packet came from.
     * @param     i an InetAddress object
     * @return    the port number which the packet came from.
     * @throws    IOException if an I/O exception occurs
     * @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.
     */
    protected abstract int peek(InetAddress i) 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. 
Params: p – the Packet Received.
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.
Returns:    the port number which the packet came from.
Since: 1.4/**
     * Peek at the packet to see who it is from. The data is copied into the specified
     * {@code DatagramPacket}. The data is returned,
     * but not consumed, so that a subsequent peekData/receive operation
     * will see the same data.
     * @param     p the Packet Received.
     * @return    the port number which the packet came from.
     * @throws    IOException if an I/O exception occurs
     * @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.
     * @since 1.4
     */
    protected abstract int peekData(DatagramPacket p) throws IOException;
    Receive the datagram packet.
Params: 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./**
     * Receive the datagram packet.
     * @param     p the Packet Received.
     * @throws    IOException if an I/O exception occurs
     *            while receiving the datagram packet.
     * @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.
     */
    protected abstract void receive(DatagramPacket p) throws IOException;

    Set the TTL (time-to-live) option.
Params: ttl – a byte specifying the TTL value
Throws: IOException – if an I/O exception occurs while setting
the time-to-live option.
See Also: getTTL()
Deprecated: use setTimeToLive instead./**
     * Set the TTL (time-to-live) option.
     * @param ttl a byte specifying the TTL value
     *
     * @deprecated use setTimeToLive instead.
     * @throws    IOException if an I/O exception occurs while setting
     * the time-to-live option.
     * @see #getTTL()
     */
    @Deprecated
    protected abstract void setTTL(byte ttl) throws IOException;

    Retrieve the TTL (time-to-live) option.
Throws: IOException – if an I/O exception occurs
while retrieving the time-to-live option
See Also: setTTL(byte)
Deprecated: use getTimeToLive instead.
Returns: a byte representing the TTL value/**
     * Retrieve the TTL (time-to-live) option.
     *
     * @throws    IOException if an I/O exception occurs
     * while retrieving the time-to-live option
     * @deprecated use getTimeToLive instead.
     * @return a byte representing the TTL value
     * @see #setTTL(byte)
     */
    @Deprecated
    protected abstract byte getTTL() throws IOException;

    Set the TTL (time-to-live) option.
Params: 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()/**
     * Set the TTL (time-to-live) option.
     * @param ttl an {@code int} specifying the time-to-live value
     * @throws    IOException if an I/O exception occurs
     * while setting the time-to-live option.
     * @see #getTimeToLive()
     */
    protected abstract void setTimeToLive(int ttl) throws IOException;

    Retrieve the TTL (time-to-live) option.
Throws: IOException – if an I/O exception occurs
while retrieving the time-to-live option
See Also: setTimeToLive(int)
Returns: an int representing the time-to-live value/**
     * Retrieve the TTL (time-to-live) option.
     * @throws    IOException if an I/O exception occurs
     * while retrieving the time-to-live option
     * @return an {@code int} representing the time-to-live value
     * @see #setTimeToLive(int)
     */
    protected abstract int getTimeToLive() throws IOException;

    Join the multicast group.
Params: inetaddr – multicast address to join.
Throws: IOException – if an I/O exception occurs
while joining the multicast group./**
     * Join the multicast group.
     * @param inetaddr multicast address to join.
     * @throws    IOException if an I/O exception occurs
     * while joining the multicast group.
     */
    protected abstract void join(InetAddress inetaddr) throws IOException;

    Leave the multicast group.
Params: inetaddr – multicast address to leave.
Throws: IOException – if an I/O exception occurs
while leaving the multicast group./**
     * Leave the multicast group.
     * @param inetaddr multicast address to leave.
     * @throws    IOException if an I/O exception occurs
     * while leaving the multicast group.
     */
    protected abstract void leave(InetAddress inetaddr) throws IOException;

    Join the multicast group.
Params: 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/**
     * Join the multicast group.
     * @param mcastaddr address to join.
     * @param 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
     */
    protected abstract void joinGroup(SocketAddress mcastaddr,
                                      NetworkInterface netIf)
        throws IOException;

    Leave the multicast group.
Params: 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/**
     * Leave the multicast group.
     * @param mcastaddr address to leave.
     * @param 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
     */
    protected abstract void leaveGroup(SocketAddress mcastaddr,
                                       NetworkInterface netIf)
        throws IOException;

    Close the socket.
/**
     * Close the socket.
     */
    protected abstract void close();

    Gets the local port.
Returns: an int representing the local port value/**
     * Gets the local port.
     * @return an {@code int} representing the local port value
     */
    protected int getLocalPort() {
        return localPort;
    }

    Gets the datagram socket file descriptor.
Returns: a FileDescriptor object representing the datagram socket file descriptor/**
     * Gets the datagram socket file descriptor.
     * @return a {@code FileDescriptor} object representing the datagram socket
     * file descriptor
     */
    protected FileDescriptor getFileDescriptor() {
        return fd;
    }

    Called to set a socket option.
Params: name – The socket option
value – The value of the socket option. A value of null may be valid for some options.
Type parameters: <T> – The type of the socket option value
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
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.
Since: 9/**
     * Called to set a socket option.
     *
     * @implSpec
     * The default implementation of this method first checks that the given
     * socket option {@code name} is not null, then throws {@code
     * UnsupportedOperationException}. Subclasses should override this method
     * with an appropriate implementation.
     *
     * @param  <T> The type of the socket option value
     * @param  name The socket option
     * @param  value The value of the socket option. A value of {@code null}
     *              may be valid for some options.
     *
     * @throws UnsupportedOperationException if the DatagramSocketImpl does not
     *         support the option
     * @throws IllegalArgumentException if the value is not valid for
     *         the option
     * @throws IOException if an I/O error occurs, or if the socket is closed
     * @throws NullPointerException if name is {@code null}
     *
     * @since 9
     */
    protected <T> void setOption(SocketOption<T> name, T value) throws IOException {
        Objects.requireNonNull(name);
        throw new UnsupportedOperationException("'" + name + "' not supported");
    }

    Called to get a socket option.
Params: name – The socket option
Type parameters: <T> – The type of the socket option value
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
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.
Returns: the socket option
Since: 9/**
     * Called to get a socket option.
     *
     * @implSpec
     * The default implementation of this method first checks that the given
     * socket option {@code name} is not null, then throws {@code
     * UnsupportedOperationException}. Subclasses should override this method
     * with an appropriate implementation.
     *
     * @param  <T> The type of the socket option value
     * @param  name The socket option
     * @return the socket option
     *
     * @throws UnsupportedOperationException if the DatagramSocketImpl does not
     *         support the option
     * @throws IOException if an I/O error occurs, or if the socket is closed
     * @throws NullPointerException if name is {@code null}
     *
     * @since 9
     */
    protected <T> T getOption(SocketOption<T> name) throws IOException {
        Objects.requireNonNull(name);
        throw new UnsupportedOperationException("'" + name + "' not supported");
    }

    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/**
     * Returns a set of SocketOptions supported by this impl
     * and by this impl's socket (DatagramSocket or MulticastSocket)
     *
     * @implSpec
     * The default implementation of this method returns an empty set.
     * Subclasses should override this method with an appropriate implementation.
     *
     * @return a Set of SocketOptions
     *
     * @since 9
     */
    protected Set<SocketOption<?>> supportedOptions() {
        return Set.of();
    }
}

Author:	Pavani Diwanji
Implementation Note:	Sockets created with the `DatagramSocket` and `MulticastSocket` public constructors historically delegated all socket operations to a `DatagramSocketImpl` implementation named "PlainDatagramSocketImpl". `DatagramSocket` and `MulticastSocket` have since been changed to a new implementation based on `DatagramChannel`. The JDK continues to ship with the older implementation to allow code to run that depends on unspecified behavior that differs between the old and new implementations. The old implementation will be used if the Java virtual machine is started with the system property jdk.net.usePlainDatagramSocketImpl set to use the old implementation. It may also be set in the JDK's network configuration file, located in `${java.home}/conf/net.properties`. The value of the property is the string representation of a boolean. If set without a value then it defaults to `true`, hence running with `-Djdk.net.usePlainDatagramSocketImpl` or `-Djdk.net.usePlainDatagramSocketImpl=true` will configure the Java virtual machine to use the old implementation. The property and old implementation will be removed in a future version.
Since:	1.1

Params:	lport – the local port laddr – the local address
Throws:	SocketException – if there is an error in the underlying protocol, such as a TCP error.

Params:	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.

Params:	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

Params:	i – an InetAddress object
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.
Returns:	the port number which the packet came from.

Params:	p – the Packet Received.
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.
Returns:	the port number which the packet came from.
Since:	1.4

Params:	ttl – a byte specifying the TTL value
Throws:	IOException – if an I/O exception occurs while setting the time-to-live option.
See Also:	getTTL()
Deprecated:	use setTimeToLive instead.

Params:	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()

Params:	inetaddr – multicast address to join.
Throws:	IOException – if an I/O exception occurs while joining the multicast group.

Params:	inetaddr – multicast address to leave.
Throws:	IOException – if an I/O exception occurs while leaving the multicast group.

Params:	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

Params:	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

Params:	name – The socket option value – The value of the socket option. A value of `null` may be valid for some options.
Type parameters:	<T> – The type of the socket option value
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`
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.
Since:	9

Params:	name – The socket option
Type parameters:	<T> – The type of the socket option value
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`
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.
Returns:	the socket option
Since:	9

/

java/ 15/ java.base/java/net/DatagramSocketImpl.java