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} + *
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 Internet protocol 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. * *
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 Internet protocol sockets + * support the following options: *
*- * Additional (implementation specific) options may also be supported. + * + ** @@ -68,7 +74,27 @@ * *
*
Server-socket channels for Unix domain sockets support: + *
+ *+ * + *+ * + * + *
+ *+ * + * + * + *Option Name + *Description + *+ * + * + *{@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} + *The size of the socket receive buffer + *
Additional (implementation specific) options may also be supported. * *
Server-socket channels are safe for use by multiple concurrent threads. *
@@ -94,7 +120,7 @@ } /** - * Opens a server-socket channel. + * Opens a server-socket channel for an Internet protocol socket. * *The new channel is created by invoking the {@link * java.nio.channels.spi.SelectorProvider#openServerSocketChannel @@ -110,13 +136,16 @@ * * @throws IOException * If an I/O error occurs + * + * @see + * java.net.preferIPv4Stack 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. * *
The new channel is created by invoking the {@link @@ -137,6 +166,9 @@ * @throws IOException * If an I/O error occurs * + * @see + * java.net.preferIPv4Stack system property + * * @since 15 */ public static ServerSocketChannel open(ProtocolFamily family) throws IOException { @@ -180,8 +212,7 @@ * @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 @@ * listen for connections. * *
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 Internet protocol sockets, once an association + * is established then the socket remains bound until the channel is closed. * *
The {@code backlog} parameter is the maximum number of pending * connections on the socket. Its exact semantics are implementation specific. @@ -207,9 +238,25 @@ * the value {@code 0}, or a negative value, then an implementation specific * default is used. * + * @apiNote + * Binding a server socket channel for a Unix Domain 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 automatically 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 Unix Domain 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 @@ * 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 Internet protocol socket address, + * or for a Unix domain socket address if it denies + * {@link NetPermission}{@code("accessUnixDomainSocket")}. * * @since 1.7 */ @@ -251,6 +300,9 @@ * declared in the {@link java.net.ServerSocket} class.
* * @return A server socket associated with this channel + * + * @throws UnsupportedOperationException + * If the channel's socket is not an Internet protocol socket */ public abstract ServerSocket socket(); @@ -265,13 +317,15 @@ *The socket channel returned by this method, if any, will be in * blocking mode regardless of the blocking mode of this channel. * - *
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 an Internet protocol 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 Unix Domain 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 @@ /** * {@inheritDoc} - *
+ * * 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 @@ * {@link java.net.InetAddress#getLoopbackAddress loopback} address and the * local port of the channel's socket is returned. * + *
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} @@ -323,5 +384,4 @@ */ @Override public abstract SocketAddress getLocalAddress() throws IOException; - }