/*

 * Copyright (c) 2018, 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 jdk.net;

import java.net.ProtocolFamily;

import java.net.ServerSocket;

import java.net.Socket;

import java.net.StandardProtocolFamily;

import java.nio.channels.Selector;

import java.nio.channels.ServerSocketChannel;

import java.nio.channels.SocketChannel;

import java.nio.channels.spi.SelectorProvider;

import java.io.IOException;

import java.util.Objects;

import jdk.internal.net.rdma.RdmaPollSelectorProvider;

import jdk.internal.net.rdma.RdmaSocketProvider;

/**

 * Factory methods for creating RDMA-based TCP sockets and socket channels.

 *

 * <p>The {@link #openSocket(ProtocolFamily) openSocket} and {@link

 * #openServerSocket(ProtocolFamily) openServerSocket} methods create RDMA-based

 * TCP sockets.

 *

 * <p>The {@link #openSelector() openSelector}, {@link

 * #openSocketChannel(ProtocolFamily) openSocketChannel}, and {@link

 * #openServerSocketChannel(ProtocolFamily) openServerSocketChannel} methods

 * create selectors and selectable channels for use with RDMA sockets. These

 * selectors and channels are created by the RDMA selector provider, which is

 * not the {@linkplain SelectorProvider#provider() default} system-wide selector

 * provider. Consequently, selectable channels to RDMA sockets may not be

 * multiplexed with selectable channels created by the default system-wide

 * selector provider. The RDMA selector provider does not support datagram

 * channels or pipes. Its {@link SelectorProvider#openDatagramChannel

 * openDatagramChannel} and {@link SelectorProvider#openPipe openPipe} methods

 * throw {@link UnsupportedOperationException UnsupportedOperationException}.

 *

 * @implNote The RDMA selector provider supports socket channels of type

 * {@link StandardProtocolFamily#INET INET} and {@link

 * StandardProtocolFamily#INET6 INET6}. Its {@link

 * SelectorProvider#openSocketChannel() openSocketChannel} and {@link

 * SelectorProvider#openServerSocketChannel() openServerSocketChannel}

 * methods create selectable channels with a family of {@link

 * StandardProtocolFamily#INET6 INET6}, if the underlying platform supports

 * IPv6. Otherwise, it creates selectable channels with a family of {@link

 * StandardProtocolFamily#INET INET}.

 *

 * @since 13

 */

public class RdmaSockets {

    private RdmaSockets() {}

    /**

     * Creates an unbound and unconnected RDMA socket.

     *

     * <p> An RDMA socket supports the same socket options that {@link

     * java.net.Socket java.net.Socket} defines. In addition, it supports the

     * socket options specified by {@link RdmaSocketOptions}.

     *

     * <p> When binding the socket to a local address, or invoking {@code

     * connect} to connect the socket, the socket address specified to those

     * methods must correspond to the protocol family specified here.

     *

     * @param   family

     *          The protocol family

     *

     * @throws IOException

     *         If an I/O error occurs

     * @throws NullPointerException

     * @throws UnsupportedOperationException

     *         If RDMA sockets are not supported on this platform or if the

     *         specified protocol family is not supported. For example, if

     *         the parameter is {@link java.net.StandardProtocolFamily#INET6

     *         StandardProtocolFamily.INET6} but IPv6 is not enabled on the

     *         platform.

     */

    public static Socket openSocket(ProtocolFamily family) throws IOException {

        Objects.requireNonNull(family, "protocol family is null");

        return RdmaSocketProvider.openSocket(family);

    }

    /**

     * Creates an unbound RDMA server socket.

     *

     * <p> An RDMA socket supports the same socket options that {@link

     * java.net.ServerSocket java.net.ServerSocket} defines.

     *

     * <p> When binding the socket to an address, the socket address specified

     * to the {@code bind} method must correspond to the protocol family

     * specified here.

     *

     * @param   family

     *          The protocol family

     *

     * @throws IOException

     *         If an I/O error occurs

     * @throws NullPointerException

     * @throws UnsupportedOperationException

     *         If RDMA sockets are not supported on this platform or if the

     *         specified protocol family is not supported. For example, if

     *         the parameter is {@link java.net.StandardProtocolFamily#INET6

     *         StandardProtocolFamily.INET6} but IPv6 is not enabled on the

     *         platform.

     */

    public static ServerSocket openServerSocket(ProtocolFamily family)

            throws IOException {

        Objects.requireNonNull(family, "protocol family is null");

        return RdmaSocketProvider.openServerSocket(family);

    }

    /**

     * Opens a socket channel to an RDMA socket. A newly created socket channel

     * is {@link SocketChannel#isOpen() open}, not yet bound to a {@link

     * SocketChannel#getLocalAddress() local address}, and not yet

     * {@link SocketChannel#isConnected() connected}.

     *

     * <p> A socket channel to an RDMA socket supports all of the socket options

     *

     * <p> When binding the channel's socket to a local address, or invoking

     * {@code connect} to connect channel's socket, the socket address specified

     * to those methods must correspond to the protocol family specified here.

     *

     * @param   family

     *          The protocol family

     *

     * @throws IOException

     *         If an I/O error occurs

     * @throws NullPointerException

     * @throws UnsupportedOperationException

     *         If RDMA sockets are not supported on this platform or if the

     *         specified protocol family is not supported. For example, if

     *         the parameter is {@link java.net.StandardProtocolFamily#INET6

     *         StandardProtocolFamily.INET6} but IPv6 is not enabled on the

     *         platform.

     */

    public static SocketChannel openSocketChannel(ProtocolFamily family)

            throws IOException {

        Objects.requireNonNull(family, "protocol family is null");

        return RdmaPollSelectorProvider.provider().openSocketChannel(family);

    }

    /**

     * Opens a server socket channel to an RDMA socket. A newly created socket

     * channel is {@link SocketChannel#isOpen() open} but not yet bound to a

     * {@link SocketChannel#getLocalAddress() local address}.

     *

     * <p> When binding the channel's socket to an address, the socket address

     * specified to the {@code bind} method must correspond to the protocol

     * family specified here.

     *

     * @param   family

     *          The protocol family

     *

     * @throws IOException

     *         If an I/O error occurs

     * @throws NullPointerException

     * @throws UnsupportedOperationException

     *         If RDMA sockets are not supported on this platform or if the

     *         specified protocol family is not supported. For example, if

     *         the parameter is {@link java.net.StandardProtocolFamily#INET6

     *         StandardProtocolFamily.INET6} but IPv6 is not enabled on the

     *         platform.

     */

    public static ServerSocketChannel openServerSocketChannel(

            ProtocolFamily family) throws IOException {

        Objects.requireNonNull(family, "protocol family is null");

        return RdmaPollSelectorProvider.provider().openServerSocketChannel(family);

    }

    /**

     * Opens a selector to multiplex selectable channels to RDMA sockets.

     *

     * @throws IOException

     *         If an I/O error occurs

     * @throws UnsupportedOperationException

     *         If RDMA sockets are not supported on this platform

     */

    public static Selector openSelector() throws IOException {

        return RdmaPollSelectorProvider.provider().openSelector();

    }

}