Summary

Add an API to the jdk.net module to create a java.nio.channels.SelectableChannel to an existing file descriptor.

Problem

A long-standing requirement is the ability to create a custom SelectableChannel implementation and have it be associated with the default SelectorProvider so that it can be used with the built-in Selector implementations.

Solution

Introduce a minimal API to create a SelectableChannel to an existing file descriptor. The resulting channel is associated with the default SelectorProvider and supports an operation-set of SelectionKey.OP_READ and SelectionKey.OP_WRITE.

The minimal API consists of one class (with one static factory method) and one interface (with two methods). The API is proposed to be added to the package jdk.nio in the module jdk.net.

Specification

package jdk.nio;

/**
 * Defines static methods to create {@link java.nio.channels.Channel channels}.
 *
 * <p> Unless otherwise specified, passing a {@code null} argument to any of the
 * methods defined here will cause a {@code NullPointerException} to be thrown.
 *
 * @since 11
 */

public final class Channels {
    private Channels() { }

    /**
     * An object used to coordinate the closing of a selectable channel created
     * by {@link Channels#readWriteSelectableChannel readWriteSelectableChannel}.
     *
     * @since 11
     */
    public interface SelectableChannelCloser {

        /**
         * Closes a selectable channel.
         *
         * <p> This method is invoked by the channel's close method in order to
         * perform the actual work of closing the channel. This method is only
         * invoked if the channel has not yet been closed, and it is never
         * invoked more than once by the channel's close implementation.
         *
         * <p> An implementation of this method must arrange for any other
         * thread that is blocked in an I/O operation upon the channel to return
         * immediately, either by throwing an exception or by returning normally.
         * If the channel is {@link SelectableChannel#isRegistered registered}
         * with one or more {@link java.nio.channels.Selector Selector}s then
         * the file descriptor should not be released until the {@link
         * #implReleaseChannel implReleaseChannel} method is invoked. </p>
         *
         * @param  sc
         *         The selectable channel
         *
         * @throws IOException
         *         If an I/O error occurs while closing the file descriptor
         *
         * @see java.nio.channels.spi.AbstractInterruptibleChannel#implCloseChannel
         */
        void implCloseChannel(SelectableChannel sc) throws IOException;

        /**
         * Release the file descriptor and any resources for a selectable
         * channel that closed while registered with one or more {@link
         * java.nio.channels.Selector Selectors}.
         *
         * <p> This method is for cases where a channel is closed when
         * {@link java.nio.channels.SelectableChannel#isRegistered registered}
         * with one or more {@code Selector}s. A channel may remain registered
         * for some time after it is closed. This method is invoked when the
         * channel is eventually deregistered from the last {@code Selector}
         * that it was registered with. It is invoked at most once.
         *
         * @apiNote This method is invoked while synchronized on the selector
         * and its selected-key set. Great care must be taken to avoid deadlocks
         * with other threads that also synchronize on these objects.
         *
         * @param  sc
         *         The closed selectable channel
         *
         * @throws IOException
         *         If an I/O error occurs
         *
         * @see java.nio.channels.spi.AbstractSelector#deregister
         */
        void implReleaseChannel(SelectableChannel sc) throws IOException;
    }

    /**
     * Creates a selectable channel to a file descriptor that supports an
     * {@link SelectableChannel#validOps() operation-set} of
     * {@link SelectionKey#OP_READ OP_READ} and
     * {@link SelectionKey#OP_WRITE OP_WRITE}. The selectable channel will be
     * created by the default {@link SelectorProvider}.
     *
     * <p> The given file descriptor is a socket or resource that can be
     * multiplexed by a {@link java.nio.channels.Selector} for read and write
     * readiness. Great care is required to coordinate direct use of the file
     * descriptor with the use of the selectable channel. In particular,
     * changing the blocking mode or closing the file descriptor without careful
     * coordination will result in unspecified and unsafe side effects. The
     * given {@link SelectableChannelCloser SelectableChannelCloser} is invoked to
     * close the file descriptor and to coordinate the closing when the channel
     * is registered with a {@code Selector}. </p>
     *
     * <p> If there is a security manager set then its
     * {@link SecurityManager#checkRead(FileDescriptor) checkRead} and
     * {@link SecurityManager#checkWrite(FileDescriptor) checkWrite} methods
     * are invoked to check that the caller has permission to both read from and
     * write to the file descriptor. </p>
     *
     * @implNote This method throws {@code UnsupportedOperationException} if
     * if the default {@code SelectorProvider} is not the JDK built-in
     * implementation.
     *
     * @param  fd
     *         The file descriptor
     * @param  closer
     *         The object to close the channel
     *
     * @return The selectable channel
     *
     * @throws IllegalArgumentException
     *         If the file descriptor is not {@link FileDescriptor#valid() valid}
     * @throws SecurityException
     *         If denied by the security manager
     */
    public static SelectableChannel readWriteSelectableChannel
        (FileDescriptor fd, SelectableChannelCloser closer) { ... }