archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8245194: Unix domain socket channel implementation

Browse source 
Reviewed-by: erikj, dfuchs, alanb, chegar
This commit is contained in:
Michael McMahon 2020-10-28 17:26:26 +00:00
parent 8bde2f4e3d
commit 6bb7e45e8e
73 changed files with 5434 additions and 1116 deletions
Download patch file Download diff file Expand all files Collapse all files

10
src/java.base/share/classes/java/nio/channels/DatagramChannel.java
View file

@ -150,6 +150,9 @@ public abstract class DatagramChannel
*
* @throws IOException
* If an I/O error occurs
*
* @see <a href="../../net/doc-files/net-properties.html#Ipv4IPv6">
* java.net.preferIPv4Stack</a> system property
*/
public static DatagramChannel open() throws IOException {
return SelectorProvider.provider().openDatagramChannel();
@ -169,6 +172,9 @@ public abstract class DatagramChannel
* java.nio.channels.spi.SelectorProvider} object. The channel will not be
* connected.
*
* @apiNote <a href="package-summary.html#unixdomain">Unix domain</a> sockets
* are not supported by DatagramChannel.
*
* @param family
* The protocol family
*
@ -182,6 +188,9 @@ public abstract class DatagramChannel
* @throws IOException
* If an I/O error occurs
*
* @see <a href="../../net/doc-files/net-properties.html#Ipv4IPv6">
* java.net.preferIPv4Stack</a> system property
*
* @since 1.7
*/
public static DatagramChannel open(ProtocolFamily family) throws IOException {
@ -629,5 +638,4 @@ public abstract class DatagramChannel
*/
@Override
public abstract SocketAddress getLocalAddress() throws IOException;
}

118
src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java
View file

@ -26,10 +26,12 @@
package java.nio.channels;
import java.io.IOException;
import java.net.NetPermission;
import java.net.ProtocolFamily;
import java.net.ServerSocket;
import java.net.SocketOption;
import java.net.SocketAddress;
import java.net.UnixDomainSocketAddress;
import java.nio.channels.spi.AbstractSelectableChannel;
import java.nio.channels.spi.SelectorProvider;
import static java.util.Objects.requireNonNull;
@ -37,16 +39,20 @@ import static java.util.Objects.requireNonNull;
/**
* A selectable channel for stream-oriented listening sockets.
*
* <p> A server-socket channel is created by invoking the {@link #open() open}
* method of this class. It is not possible to create a channel for an arbitrary,
* pre-existing {@link ServerSocket}. A newly-created server-socket channel is
* open but not yet bound. An attempt to invoke the {@link #accept() accept}
* method of an unbound server-socket channel will cause a {@link NotYetBoundException}
* <p> A server-socket channel is created by invoking one of the {@code open}
* methods of this class. The no-arg {@link #open() open} method opens a server-socket
* channel for an <i>Internet protocol</i> socket. The {@link #open(ProtocolFamily)}
* method is used to open a server-socket channel for a socket of a specified
* protocol family. It is not possible to create a channel for an arbitrary,
* pre-existing socket. A newly-created server-socket channel is open but not yet
* bound. An attempt to invoke the {@link #accept() accept} method of an
* unbound server-socket channel will cause a {@link NotYetBoundException}
* to be thrown. A server-socket channel can be bound by invoking one of the
* {@link #bind(java.net.SocketAddress,int) bind} methods defined by this class.
* {@link #bind(java.net.SocketAddress, int) bind} methods defined by this class.
*
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
* setOption} method. Server-socket channels support the following options:
* setOption} method. Server-socket channels for <i>Internet protocol</i> sockets
* support the following options:
* <blockquote>
* <table class="striped">
* <caption style="display:none">Socket options</caption>
@ -68,7 +74,27 @@ import static java.util.Objects.requireNonNull;
* </tbody>
* </table>
* </blockquote>
* Additional (implementation specific) options may also be supported.
*
* <p> Server-socket channels for <i>Unix domain</i> sockets support:
* <blockquote>
* <table class="striped">
* <caption style="display:none">Socket options</caption>
* <thead>
* <tr>
* <th scope="col">Option Name</th>
* <th scope="col">Description</th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row"> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </th>
* <td> The size of the socket receive buffer </td>
* </tr>
* </tbody>
* </table>
* </blockquote>
*
* <p> Additional (implementation specific) options may also be supported.
*
* <p> Server-socket channels are safe for use by multiple concurrent threads.
* </p>
@ -94,7 +120,7 @@ public abstract class ServerSocketChannel
}
/**
* Opens a server-socket channel.
* Opens a server-socket channel for an <i>Internet protocol</i> socket.
*
* <p> The new channel is created by invoking the {@link
* java.nio.channels.spi.SelectorProvider#openServerSocketChannel
@ -110,13 +136,16 @@ public abstract class ServerSocketChannel
*
* @throws IOException
* If an I/O error occurs
*
* @see <a href="../../net/doc-files/net-properties.html#Ipv4IPv6">
* java.net.preferIPv4Stack</a> system property
*/
public static ServerSocketChannel open() throws IOException {
return SelectorProvider.provider().openServerSocketChannel();
}
/**
* Opens a server-socket channel.The {@code family} parameter specifies the
* Opens a server-socket channel. The {@code family} parameter specifies the
* {@link ProtocolFamily protocol family} of the channel's socket.
*
* <p> The new channel is created by invoking the {@link
@ -137,6 +166,9 @@ public abstract class ServerSocketChannel
* @throws IOException
* If an I/O error occurs
*
* @see <a href="../../net/doc-files/net-properties.html#Ipv4IPv6">
* java.net.preferIPv4Stack</a> system property
*
* @since 15
*/
public static ServerSocketChannel open(ProtocolFamily family) throws IOException {
@ -180,8 +212,7 @@ public abstract class ServerSocketChannel
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
* @throws SecurityException
* If a security manager has been installed and its {@link
* SecurityManager#checkListen checkListen} method denies the
* If a security manager has been installed and it denies the
* operation
*
* @since 1.7
@ -197,8 +228,8 @@ public abstract class ServerSocketChannel
* listen for connections.
*
* <p> This method is used to establish an association between the socket and
* a local address. Once an association is established then the socket remains
* bound until the channel is closed.
* a local address. For <i>Internet protocol</i> sockets, once an association
* is established then the socket remains bound until the channel is closed.
*
* <p> The {@code backlog} parameter is the maximum number of pending
* connections on the socket. Its exact semantics are implementation specific.
@ -207,9 +238,25 @@ public abstract class ServerSocketChannel
* the value {@code 0}, or a negative value, then an implementation specific
* default is used.
*
* @apiNote
* Binding a server socket channel for a <i>Unix Domain</i> socket, creates a
* file corresponding to the file path in the {@link UnixDomainSocketAddress}.
* This file persists after the channel is closed, and must be removed before
* another socket can bind to the same name. Binding to a {@code null} address
* causes the socket to be <i>automatically</i> bound to some unique file
* in a system temporary location. The associated socket file also persists
* after the channel is closed. Its name can be obtained from the channel's
* local socket address.
*
* @implNote
* Each platform enforces an implementation specific, maximum length for the
* name of a <i>Unix Domain</i> socket. This limitation is enforced when a
* channel is bound. The maximum length is typically close to and generally
* not less than 100 bytes.
*
* @param local
* The address to bind the socket, or {@code null} to bind to an
* automatically assigned socket address
* The address to bind the socket, or {@code null} to bind to
* an automatically assigned socket address
* @param backlog
* The maximum number of pending connections
*
@ -225,8 +272,10 @@ public abstract class ServerSocketChannel
* If some other I/O error occurs
* @throws SecurityException
* If a security manager has been installed and its {@link
* SecurityManager#checkListen checkListen} method denies the
* operation
* SecurityManager#checkListen checkListen} method denies
* the operation for an <i>Internet protocol</i> socket address,
* or for a <i>Unix domain</i> socket address if it denies
* {@link NetPermission}{@code("accessUnixDomainSocket")}.
*
* @since 1.7
*/
@ -251,6 +300,9 @@ public abstract class ServerSocketChannel
* declared in the {@link java.net.ServerSocket} class. </p>
*
* @return A server socket associated with this channel
*
* @throws UnsupportedOperationException
* If the channel's socket is not an <i>Internet protocol</i> socket
*/
public abstract ServerSocket socket();
@ -265,13 +317,15 @@ public abstract class ServerSocketChannel
* <p> The socket channel returned by this method, if any, will be in
* blocking mode regardless of the blocking mode of this channel.
*
* <p> This method performs exactly the same security checks as the {@link
* java.net.ServerSocket#accept accept} method of the {@link
* java.net.ServerSocket} class. That is, if a security manager has been
* installed then for each new connection this method verifies that the
* address and port number of the connection's remote endpoint are
* permitted by the security manager's {@link
* java.lang.SecurityManager#checkAccept checkAccept} method. </p>
* <p> If bound to an <i>Internet protocol</i> socket address, this method
* performs exactly the same security checks as the {@link
* java.net.ServerSocket#accept accept} method of the {@link java.net.ServerSocket}
* class. That is, if a security manager has been installed then for each
* new connection this method verifies that the address and port number
* of the connection's remote endpoint are permitted by the security
* manager's {@link java.lang.SecurityManager#checkAccept checkAccept}
* method. If bound to a <i>Unix Domain</i> socket address, this method checks
* {@link NetPermission}{@code ("accessUnixDomainSocket")}.
*
* @return The socket channel for the new connection,
* or {@code null} if this channel is in non-blocking mode
@ -305,7 +359,7 @@ public abstract class ServerSocketChannel
/**
* {@inheritDoc}
* <p>
*
* If there is a security manager set, its {@code checkConnect} method is
* called with the local address and {@code -1} as its arguments to see
* if the operation is allowed. If the operation is not allowed,
@ -313,9 +367,16 @@ public abstract class ServerSocketChannel
* {@link java.net.InetAddress#getLoopbackAddress loopback} address and the
* local port of the channel's socket is returned.
*
* <p> Where the channel is bound to a <i>Unix Domain</i> socket address, the socket
* address is a {@link UnixDomainSocketAddress}. If there is a security manager
* set, its {@link SecurityManager#checkPermission(java.security.Permission)
* checkPermission} method is called with {@link NetPermission}{@code
* ("accessUnixDomainSocket")}. If the operation is not allowed an unnamed
* {@link UnixDomainSocketAddress} is returned.
*
* @return The {@code SocketAddress} that the socket is bound to, or the
* {@code SocketAddress} representing the loopback address if
* denied by the security manager, or {@code null} if the
* {@code SocketAddress} representing the loopback address or empty
* path if denied by the security manager, or {@code null} if the
* channel's socket is not bound
*
* @throws ClosedChannelException {@inheritDoc}
@ -323,5 +384,4 @@ public abstract class ServerSocketChannel
*/
@Override
public abstract SocketAddress getLocalAddress() throws IOException;
}

181
src/java.base/share/classes/java/nio/channels/SocketChannel.java
View file

@ -26,10 +26,14 @@
package java.nio.channels;
import java.io.IOException;
import java.net.InetSocketAddress;
import java.net.NetPermission;
import java.net.ProtocolFamily;
import java.net.StandardProtocolFamily;
import java.net.Socket;
import java.net.SocketOption;
import java.net.SocketAddress;
import java.net.UnixDomainSocketAddress;
import java.nio.ByteBuffer;
import java.nio.channels.spi.AbstractSelectableChannel;
import java.nio.channels.spi.SelectorProvider;
@ -38,15 +42,18 @@ import static java.util.Objects.requireNonNull;
/**
* A selectable channel for stream-oriented connecting sockets.
*
* <p> A socket channel is created by invoking one of the {@link #open open}
* methods of this class. It is not possible to create a channel for an arbitrary,
* pre-existing socket. A newly-created socket channel is open but not yet
* connected. An attempt to invoke an I/O operation upon an unconnected
* channel will cause a {@link NotYetConnectedException} to be thrown. A
* socket channel can be connected by invoking its {@link #connect connect}
* method; once connected, a socket channel remains connected until it is
* closed. Whether or not a socket channel is connected may be determined by
* invoking its {@link #isConnected isConnected} method.
* <p> A socket channel is created by invoking one of the {@code open} methods of
* this class. The no-arg {@link #open() open} method opens a socket channel
* for an <i>Internet protocol</i> socket. The {@link #open(ProtocolFamily)}
* method is used to open a socket channel for a socket of a specified protocol
* family. It is not possible to create a channel for an arbitrary, pre-existing
* socket. A newly-created socket channel is open but not yet connected. An
* attempt to invoke an I/O operation upon an unconnected channel will cause a
* {@link NotYetConnectedException} to be thrown. A socket channel can be
* connected by invoking its {@link #connect connect} method; once connected,
* a socket channel remains connected until it is closed. Whether or not a
* socket channel is connected may be determined by invoking its {@link #isConnected()
* isConnected} method.
*
* <p> Socket channels support <i>non-blocking connection:</i>&nbsp;A socket
* channel may be created and the process of establishing the link to the
@ -55,7 +62,7 @@ import static java.util.Objects.requireNonNull;
* Whether or not a connection operation is in progress may be determined by
* invoking the {@link #isConnectionPending isConnectionPending} method.
*
* <p> Socket channels support <i>asynchronous shutdown,</i> which is similar
* <p> Socket channels support <i>asynchronous shutdown</i>, which is similar
* to the asynchronous close operation specified in the {@link Channel} class.
* If the input side of a socket is shut down by one thread while another
* thread is blocked in a read operation on the socket's channel, then the read
@ -66,7 +73,8 @@ import static java.util.Objects.requireNonNull;
* AsynchronousCloseException}.
*
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
* setOption} method. Socket channels support the following options:
* setOption} method. Socket channels for <i>Internet protocol</i> sockets support
* following options:
* <blockquote>
* <table class="striped">
* <caption style="display:none">Socket options</caption>
@ -105,7 +113,36 @@ import static java.util.Objects.requireNonNull;
* </tbody>
* </table>
* </blockquote>
* Additional (implementation specific) options may also be supported.
*
* <p> Socket channels for <i>Unix domain</i> sockets support:
* <blockquote>
* <table class="striped">
* <caption style="display:none">Socket options</caption>
* <thead>
* <tr>
* <th scope="col">Option Name</th>
* <th scope="col">Description</th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row"> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </th>
* <td> The size of the socket send buffer </td>
* </tr>
* <tr>
* <th scope="row"> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </th>
* <td> The size of the socket receive buffer </td>
* </tr>
* <tr>
* <th scope="row"> {@link java.net.StandardSocketOptions#SO_LINGER SO_LINGER} </th>
* <td> Linger on close if data is present (when configured in blocking mode
* only) </td>
* </tr>
* </tbody>
* </table>
* </blockquote>
*
* <p> Additional (implementation specific) options may also be supported.
*
* <p> Socket channels are safe for use by multiple concurrent threads. They
* support concurrent reading and writing, though at most one thread may be
@ -136,7 +173,7 @@ public abstract class SocketChannel
}
/**
* Opens a socket channel.
* Opens a socket channel for an <i>Internet protocol</i> socket.
*
* <p> The new channel is created by invoking the {@link
* java.nio.channels.spi.SelectorProvider#openSocketChannel
@ -147,6 +184,9 @@ public abstract class SocketChannel
*
* @throws IOException
* If an I/O error occurs
*
* @see <a href="../../net/doc-files/net-properties.html#Ipv4IPv6">
* java.net.preferIPv4Stack</a> system property
*/
public static SocketChannel open() throws IOException {
return SelectorProvider.provider().openSocketChannel();
@ -174,6 +214,9 @@ public abstract class SocketChannel
* @throws IOException
* If an I/O error occurs
*
* @see <a href="../../net/doc-files/net-properties.html#Ipv4IPv6">
* java.net.preferIPv4Stack</a> system property
*
* @since 15
*/
public static SocketChannel open(ProtocolFamily family) throws IOException {
@ -183,10 +226,16 @@ public abstract class SocketChannel
/**
* Opens a socket channel and connects it to a remote address.
*
* <p> This convenience method works as if by invoking the {@link #open()}
* method, invoking the {@link #connect(SocketAddress) connect} method upon
* the resulting socket channel, passing it {@code remote}, and then
* returning that channel. </p>
* <p> If the remote address is an {@link InetSocketAddress} then this
* method works as if by invoking the {@link #open()} method, invoking the
* {@link #connect(SocketAddress) connect} method upon the resulting socket
* channel, passing it {@code remote}, and then returning that channel.
*
* <p> If the remote address is a {@link UnixDomainSocketAddress} then this
* works by invoking the {@link #open(ProtocolFamily)} method with {@link
* StandardProtocolFamily#UNIX} as parameter, invoking the {@link
* #connect(SocketAddress) connect} method upon the resulting socket channel,
* passing it {@code remote}, then returning that channel. </p>
*
* @param remote
* The remote address to which the new channel is to be connected
@ -204,7 +253,8 @@ public abstract class SocketChannel
* interrupt status
*
* @throws UnresolvedAddressException
* If the given remote address is not fully resolved
* If the given remote address is an InetSocketAddress that is not fully
* resolved
*
* @throws UnsupportedAddressTypeException
* If the type of the given remote address is not supported
@ -215,11 +265,22 @@ public abstract class SocketChannel
*
* @throws IOException
* If some other I/O error occurs
*
* @see <a href="../../net/doc-files/net-properties.html#Ipv4IPv6">
* java.net.preferIPv4Stack</a> system property
*/
public static SocketChannel open(SocketAddress remote)
throws IOException
{
SocketChannel sc = open();
SocketChannel sc;
requireNonNull(remote);
if (remote instanceof InetSocketAddress)
sc = open();
else if (remote instanceof UnixDomainSocketAddress)
sc = open(StandardProtocolFamily.UNIX);
else
throw new UnsupportedAddressTypeException();
try {
sc.connect(remote);
} catch (Throwable x) {
@ -255,6 +316,38 @@ public abstract class SocketChannel
// -- Socket-specific operations --
/**
* Binds the channel's socket to a local address.
*
* <p> This method is used to establish an association between the socket
* and a local address. For <i>Internet Protocol</i> sockets, once an
* association is established then the socket remains bound until the
* channel is closed. If the {@code local} parameter has the value {@code
* null} then the socket will be bound to an address that is assigned
* automatically.
*
* @apiNote
* Binding a socket channel to a <i>Unix Domain</i> socket creates a file
* corresponding to the file path in the {@link UnixDomainSocketAddress}. This
* file persists after the channel is closed, and must be removed before
* another socket can bind to the same name. If a socket channel to a Unix
* Domain socket is <i>implicitly</i> bound by connecting it without calling
* bind first, then its socket is
* <a href="../../java/net/UnixDomainSocketAddress.html#unnamed">unnamed</a>
* with no corresponding socket file in the file-system. If a socket channel
* to a Unix Domain socket is <i>automatically</i> bound by calling {@code
* bind(null)} this results in an unnamed socket also.
*
* @implNote
* Each platform enforces an implementation specific maximum length for the
* name of a <i>Unix Domain</i> socket. This limitation is enforced when a
* channel is bound. The maximum length is typically close to and generally
* not less than 100 bytes.
*
* @param local The address to bind the socket, or {@code null} to bind
* the socket to an automatically assigned socket address
*
* @return This channel
*
* @throws ConnectionPendingException
* If a non-blocking connect operation is already in progress on
* this channel
@ -263,9 +356,11 @@ public abstract class SocketChannel
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
* @throws SecurityException
* If a security manager has been installed and its
* {@link SecurityManager#checkListen checkListen} method denies
* the operation
* If a security manager has been installed and its {@link
* SecurityManager#checkListen checkListen} method denies
* the operation for an <i>Internet protocol</i> socket address,
* or for a <i>Unix domain</i> socket address if it denies
* {@link NetPermission}{@code("accessUnixDomainSocket")}.
*
* @since 1.7
*/
@ -329,10 +424,10 @@ public abstract class SocketChannel
/**
* Retrieves a socket associated with this channel.
*
* <p> The returned object will not declare any public methods that are not
* declared in the {@link java.net.Socket} class. </p>
*
* @return A socket associated with this channel
*
* @throws UnsupportedOperationException
* If the channel's socket is not an <i>Internet protocol</i> socket
*/
public abstract Socket socket();
@ -368,12 +463,19 @@ public abstract class SocketChannel
* method will block until the connection is established or an I/O error
* occurs.
*
* <p> This method performs exactly the same security checks as the {@link
* java.net.Socket} class. That is, if a security manager has been
* <p> For channels to <i>Internet protocol</i> sockets, this method performs
* exactly the same security checks as the {@link java.net.Socket} class.
* That is, if a security manager has been
* installed then this method verifies that its {@link
* java.lang.SecurityManager#checkConnect checkConnect} method permits
* connecting to the address and port number of the given remote endpoint.
*
* <p> For channels to <i>Unix Domain</i> sockets, this method checks
* {@link java.net.NetPermission NetPermission}{@code
* ("accessUnixDomainSocket")} with the security manager's {@link
* SecurityManager#checkPermission(java.security.Permission)
* checkPermission} method.
*
* <p> This method may be invoked at any time. If a read or write
* operation upon this channel is invoked while an invocation of this
* method is in progress then that operation will first block until this
@ -409,7 +511,7 @@ public abstract class SocketChannel
* interrupt status
*
* @throws UnresolvedAddressException
* If the given remote address is not fully resolved
* If the given remote address is an InetSocketAddress that is not fully resolved
*
* @throws UnsupportedAddressTypeException
* If the type of the given remote address is not supported
@ -477,9 +579,12 @@ public abstract class SocketChannel
/**
* Returns the remote address to which this channel's socket is connected.
*
* <p> Where the channel is bound and connected to an Internet Protocol
* socket address then the return value from this method is of type {@link
* java.net.InetSocketAddress}.
* <p> Where the channel's socket is bound and connected to an <i>Internet
* Protocol</i> socket address then the return value is of type
* {@link java.net.InetSocketAddress}.
*
* <p> Where the channel's socket is bound and connected to a <i>Unix Domain</i>
* socket address, the returned address is a {@link UnixDomainSocketAddress}.
*
* @return The remote address; {@code null} if the channel's socket is not
* connected
@ -539,7 +644,7 @@ public abstract class SocketChannel
/**
* {@inheritDoc}
* <p>
*
* If there is a security manager set, its {@code checkConnect} method is
* called with the local address and {@code -1} as its arguments to see
* if the operation is allowed. If the operation is not allowed,
@ -547,9 +652,16 @@ public abstract class SocketChannel
* {@link java.net.InetAddress#getLoopbackAddress loopback} address and the
* local port of the channel's socket is returned.
*
* <p> Where the channel is bound to a Unix Domain socket address, the socket
* address is a {@link UnixDomainSocketAddress}. If there is a security manager
* set, its {@link SecurityManager#checkPermission(java.security.Permission)
* checkPermission} method is called with {@link NetPermission}{@code
* ("accessUnixDomainSocket")}. If the operation is not allowed an unnamed
* {@link UnixDomainSocketAddress} is returned.
*
* @return The {@code SocketAddress} that the socket is bound to, or the
* {@code SocketAddress} representing the loopback address if
* denied by the security manager, or {@code null} if the
* {@code SocketAddress} representing the loopback address or empty
* path if denied by the security manager, or {@code null} if the
* channel's socket is not bound
*
* @throws ClosedChannelException {@inheritDoc}
@ -557,5 +669,4 @@ public abstract class SocketChannel
*/
@Override
public abstract SocketAddress getLocalAddress() throws IOException;
}

24
src/java.base/share/classes/java/nio/channels/package-info.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2020, 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
@ -241,6 +241,28 @@
* If a channel needs an associated socket then a socket will be created as a side
* effect of this operation.
*
* <p> {@link java.nio.channels.DatagramChannel},
* {@link java.nio.channels.SocketChannel} and
* {@link java.nio.channels.ServerSocketChannel}s can be created
* with different {@link java.net.ProtocolFamily protocol families}. The standard
* family types are specified in {@link java.net.StandardProtocolFamily}.
*
* <p> Channels for <i>Internet Protocol</i> sockets are created using the
* {@link java.net.StandardProtocolFamily#INET INET} or {@link
* java.net.StandardProtocolFamily#INET6 INET6} protocol families. <i>Internet
* Protocol</i> sockets support network communication using TCP and UDP and are
* addressed using {@link java.net.InetSocketAddress}es which encapsulate an IP
* address and port number. <i>Internet Protocol</i> sockets are also the default
* type created, when a protocol family is not specified in the channel factory
* creation method.
*
* <p> Channels for <a id="unixdomain"></a><i>Unix Domain</i> sockets are created
* using the {@link java.net.StandardProtocolFamily#UNIX UNIX} protocol family.
* <i>Unix Domain</i> sockets support local inter-process
* communication on the same host, and are addressed using {@link
* java.net.UnixDomainSocketAddress}es which encapsulate a filesystem pathname
* on the local system.
*
* <p> The implementation of selectors, selectable channels, and selection keys
* can be replaced by "plugging in" an alternative definition or instance of the
* {@link java.nio.channels.spi.SelectorProvider} class defined in the {@link

36
src/java.base/share/classes/java/nio/channels/spi/SelectorProvider.java
View file

@ -268,34 +268,38 @@ public abstract class SelectorProvider {
* associated network port. In this example, the process that is started,
* inherits a channel representing a network socket.
*
* <p> In cases where the inherited channel represents a network socket
* then the {@link java.nio.channels.Channel Channel} type returned
* <p> In cases where the inherited channel is for an <i>Internet protocol</i>
* socket then the {@link Channel Channel} type returned
* by this method is determined as follows:
*
* <ul>
*
* <li><p> If the inherited channel represents a stream-oriented connected
* socket then a {@link java.nio.channels.SocketChannel SocketChannel} is
* returned. The socket channel is, at least initially, in blocking
* mode, bound to a socket address, and connected to a peer.
* <li><p> If the inherited channel is for a stream-oriented connected
* socket then a {@link SocketChannel SocketChannel} is returned. The
* socket channel is, at least initially, in blocking mode, bound
* to a socket address, and connected to a peer.
* </p></li>
*
* <li><p> If the inherited channel represents a stream-oriented listening
* socket then a {@link java.nio.channels.ServerSocketChannel
* ServerSocketChannel} is returned. The server-socket channel is, at
* least initially, in blocking mode, and bound to a socket address.
* <li><p> If the inherited channel is for a stream-oriented listening
* socket then a {@link ServerSocketChannel ServerSocketChannel} is returned.
* The server-socket channel is, at least initially, in blocking mode,
* and bound to a socket address.
* </p></li>
*
* <li><p> If the inherited channel is a datagram-oriented socket
* then a {@link java.nio.channels.DatagramChannel DatagramChannel} is
* returned. The datagram channel is, at least initially, in blocking
* mode, and bound to a socket address.
* <li><p> If the inherited channel is a datagram-oriented socket then a
* {@link DatagramChannel DatagramChannel} is returned. The datagram channel
* is, at least initially, in blocking mode, and bound to a socket address.
* </p></li>
*
* </ul>
*
* <p> In addition to the network-oriented channels described, this method
* may return other kinds of channels in the future.
* <p> In cases where the inherited channel is for a <i>Unix domain</i>
* socket then the {@link Channel} type returned is the same as for
* <i>Internet protocol</i> sockets as described above, except that
* datagram-oriented sockets are not supported.
*
* <p> In addition to the two types of socket just described, this method
* may return other types in the future.
*
* <p> The first invocation of this method creates the channel that is
* returned. Subsequent invocations of this method return the same