jdk-sandbox: comparison src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java

equal deleted inserted replaced

-:eb491334113f
+:119ac9128c1b
 */
 package java.nio.channels;
 import java.io.IOException;
+import java.net.ProtocolFamily;
+import java.net.StandardProtocolFamily;
 import java.net.ServerSocket;
 import java.net.SocketOption;
 import java.net.SocketAddress;
 import java.nio.channels.spi.AbstractSelectableChannel;
 import java.nio.channels.spi.SelectorProvider;
 /**
 * A selectable channel for stream-oriented listening sockets.
 *
-* <p> A server-socket channel is created by invoking the {@link #open() open}
+* <p> A server-socket channel is created by invoking the open methods of this class.
-* method of this class.  It is not possible to create a channel for an arbitrary,
+* 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}
 * 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.
 *
+* <p>Two kinds of server-socket channel are supported: <i>IP</i> (Internet Protocol)
+* and <i>unix domain</i> depending on which open method is used to create them and which subtype of
+* {@link SocketAddress} that they support for local and remote addresses.
+* <i>IP</i> channels are created using {@link #open()}. They use {@link
+* InetSocketAddress} addresses and support both IPv4 and IPv6 TCP/IP.
+* <i>unix domain</i> channels are created using {@link #open(ProtocolFamily)}
+* with the family parameter set to {@link StandardProtocolFamily#UNIX}.
+* They use {@link UnixDomainSocketAddress}es and also
+* do not support the {@link #socket()} method.
+*
 * <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
-* setOption} method. Server-socket channels support the following options:
+* setOption} method. <i>IP</i> server-socket channels support the following options:
 * <blockquote>
 * <table class="striped">
 * <caption style="display:none">Socket options</caption>
 * <thead>
 *   <tr>
 *     <td> Re-use address </td>
 *   </tr>
 * </tbody>
 * </table>
 * </blockquote>
+*
 * Additional (implementation specific) options may also be supported.
 *
 * <p> Server-socket channels are safe for use by multiple concurrent threads.
 * </p>
+*
+* <p><i>Unix domain</i> server-socket channels support a subset of the options listed above.
 *
 * @author Mark Reinhold
 * @author JSR-51 Expert Group
 * @since 1.4
 */
 protected ServerSocketChannel(SelectorProvider provider) {
 super(provider);
 }
 /**
-* Opens a server-socket channel.
+* Opens an <i>IP</i> server-socket channel.
 *
 * <p> 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.
 * @throws  IOException
 *          If an I/O error occurs
 */
 public static ServerSocketChannel open() throws IOException {
 return SelectorProvider.provider().openServerSocketChannel();
+}
+/**
+* Returns a {@link ServerSocketChannel} of the given protocol family.
+* Where family is equal to {@link StandardProtocolFamily#INET} or {@link
+* StandardProtocolFamily#INET6} the returned channel must be bound to an
+* {@link InetSocketAddress}. If family is {@link StandardProtocolFamily#UNIX}
+* the returned channel must be bound to a {@link jdk.net.UnixDomainSocketAddress}
+*
+* @param family the protocol family
+*
+* @return a ServerSocketChannel
+*
+* @throws IOException if an I/O error occurs
+* @throws UnsupportedAddressTypeException if the protocol family is not supported
+* @since 14
+*/
+public static ServerSocketChannel open(ProtocolFamily family) throws IOException {
+return SelectorProvider.provider().openServerSocketChannel(family);
 }
 /**
 * Returns an operation set identifying this channel's supported
 * operations.
 * @throws  AlreadyBoundException               {@inheritDoc}
 * @throws  UnsupportedAddressTypeException     {@inheritDoc}
 * @throws  ClosedChannelException              {@inheritDoc}
 * @throws  IOException                         {@inheritDoc}
 * @throws  SecurityException
-*          If a security manager has been installed and its {@link
+*          If a security manager has been installed and its
-*          SecurityManager#checkListen checkListen} method denies the
+*          {@link SecurityManager#checkListen checkListen} method denies
-*          operation
+*          the operation for <i>IP</i> channels or for <i>unix domain</i>
+*          channels, if the security manager denies "read" or "write"
+*          {@link FilePermission} for the local path.
 *
 * @since 1.7
 */
 public final ServerSocketChannel bind(SocketAddress local)
 throws IOException
 * 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.
+*
+* <p> Note, for <i>Unix domain</i> channels, a file is created in the file-system
+* with the same name as this channel's bound address. This file persists after
+* the channel is closed, and must be removed before another channel can bind
+* to the same name.
 *
 * @param   local
 *          The address to bind the socket, or {@code null} to bind to an
 *          automatically assigned socket address
 * @param   backlog
 * @throws  ClosedChannelException
 *          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
+*          If a security manager has been installed and its
-*          SecurityManager#checkListen checkListen} method denies the
+*          {@link SecurityManager#checkListen checkListen} method denies
-*          operation
+*          the operation for <i>IP</i> channels or for <i>unix domain</i>
+*          channels, if the security manager denies "read" or "write"
+*          {@link FilePermission} for the local path.
 *
 * @since 1.7
 */
 public abstract ServerSocketChannel bind(SocketAddress local, int backlog)
 throws IOException;
 */
 public abstract <T> ServerSocketChannel setOption(SocketOption<T> name, T value)
 throws IOException;
 /**
-* Retrieves a server socket associated with this channel.
+* Retrieves a server socket associated with this channel if it is an <i>IP</i>
+* channel. The operation is not supported for <i>unix domain</i> channels.
 *
 * <p> The returned object will not declare any public methods that are not
 * declared in the {@link java.net.ServerSocket} class.  </p>
 *
 * @return  A server socket associated with this channel
+* @throws UnsupportedOperationException is this is a Unix domain channel
 */
 public abstract ServerSocket socket();
 /**
 * Accepts a connection made to this channel's socket.
 * or an I/O error occurs.
 *
 * <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
+* <p> For <i>IP</i> channels, 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> For <i>unix domain</i> channels, this method performs a security
+* manager {@link SecurityManager#checkPermission(Permission)} using
+* a {@link java.io.FilePermission} constructed with the path from the
+* remote address and "read,write" as the actions.
+*
 * @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
 *
 * @throws  ClosedChannelException
 public abstract SocketChannel accept() throws IOException;
 /**
 * {@inheritDoc}
 * <p>
-* If there is a security manager set, its {@code checkConnect} method is
+* If there is a security manager set and this is an <i>IP</i> channel,
+* {@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.
+* <p>
+* If there is a security manager set and this is an <i>unix domain</i> channel,
+* then this returns a {@link UnixDomainSocketAddress} corresponding to the
+* bound address.
 *
 * @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
 *          channel's socket is not bound

branch	unixdomainchannels
changeset 58801	119ac9128c1b
parent 47216	71c04702a3d5
child 58847	692de65ab293