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. + * + ** * *
*@@ -66,11 +72,31 @@ * * *Re-use address *
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. *
* * @author Mark Reinhold @@ -92,11 +118,11 @@ protected ServerSocketChannel(SelectorProvider provider) { super(provider); } /** - * 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 * openServerSocketChannel} method of the system-wide default {@link * java.nio.channels.spi.SelectorProvider} object. @@ -108,17 +134,20 @@ * * @return A new socket channel * * @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 * java.nio.channels.spi.SelectorProvider#openServerSocketChannel(ProtocolFamily) * openServerSocketChannel(ProtocolFamily)} method of the system-wide default {@link @@ -135,10 +164,13 @@ * java.net.StandardProtocolFamily#INET6 StandardProtocolFamily.INET6} * but IPv6 is not enabled on the platform. * @throws IOException * If an I/O error occurs * + * @see + * java.net.preferIPv4Stack system property + * * @since 15 */ public static ServerSocketChannel open(ProtocolFamily family) throws IOException { return SelectorProvider.provider().openServerSocketChannel(requireNonNull(family)); } @@ -178,12 +210,11 @@ * @throws AlreadyBoundException {@inheritDoc} * @throws UnsupportedAddressTypeException {@inheritDoc} * @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 */ public final ServerSocketChannel bind(SocketAddress local) @@ -195,23 +226,39 @@ /** * Binds the channel's socket to a local address and configures the socket to * 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. * In particular, an implementation may impose a maximum length or may choose * to ignore the parameter altogther. If the {@code backlog} parameter has * 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 * * @return This channel * @@ -223,12 +270,14 @@ * If this channel is closed * @throws IOException * 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 */ public abstract ServerSocketChannel bind(SocketAddress local, int backlog) throws IOException; @@ -249,10 +298,13 @@ * *
The returned object will not declare any public methods that are not * 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(); /** * Accepts a connection made to this channel's socket. @@ -263,17 +315,19 @@ * or an I/O error occurs. * *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 * and no connection is available to be accepted * @@ -303,25 +357,31 @@ */ public abstract SocketChannel accept() throws IOException; /** * {@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, * a {@code SocketAddress} representing the * {@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} * @throws IOException {@inheritDoc} */ @Override public abstract SocketAddress getLocalAddress() throws IOException; - }