An unnamed {@code UnixDomainSocketAddress} has + * an empty path. The local address of a {@link SocketChannel} to a Unix domain socket + * that is automatically or implicitly bound will be unnamed. + * + *
{@link Path} objects used to create instances of this class must be obtained + * from the {@linkplain FileSystems#getDefault system-default} file system. + * + * @see java.nio.channels.SocketChannel + * @see java.nio.channels.ServerSocketChannel + * @since 16 + */ +public final class UnixDomainSocketAddress extends SocketAddress { + @java.io.Serial + static final long serialVersionUID = 92902496589351288L; + + private final transient Path path; + + /** + * A serial proxy for all {@link UnixDomainSocketAddress} instances. + * It captures the file path name and reconstructs using the public static + * {@link #of(String) factory}. + * + * @serial include + */ + private static final class Ser implements Serializable { + @java.io.Serial + static final long serialVersionUID = -7955684448513979814L; + + /** + * The path name. + * @serial + */ + private final String pathname; + + Ser(String pathname) { + this.pathname = pathname; + } + + /** + * Creates a {@link UnixDomainSocketAddress} instance, by an invocation + * of the {@link #of(String) factory} method passing the path name. + * @return a UnixDomainSocketAddress + */ + @java.io.Serial + private Object readResolve() { + return UnixDomainSocketAddress.of(pathname); + } + } + + /** + * Returns a + * + * Ser containing the path name of this instance. + * + * @return a {@link Ser} + * representing the path name of this instance + */ + @java.io.Serial + private Object writeReplace() throws ObjectStreamException { + return new Ser(path.toString()); + } + + /** + * Throws InvalidObjectException, always. + * @param s the stream + * @throws java.io.InvalidObjectException always + */ + @java.io.Serial + private void readObject(java.io.ObjectInputStream s) + throws java.io.InvalidObjectException + { + throw new java.io.InvalidObjectException("Proxy required"); + } + + /** + * Throws InvalidObjectException, always. + * @throws java.io.InvalidObjectException always + */ + @java.io.Serial + private void readObjectNoData() + throws java.io.InvalidObjectException + { + throw new java.io.InvalidObjectException("Proxy required"); + } + + private UnixDomainSocketAddress(Path path) { + FileSystem fs = path.getFileSystem(); + if (fs != FileSystems.getDefault()) { + throw new IllegalArgumentException(); + } + if (fs.getClass().getModule() != Object.class.getModule()) { + throw new IllegalArgumentException(); + } + this.path = path; + } + + /** + * Create a UnixDomainSocketAddress from the given path string. + * + * @param pathname + * The path string, which can be empty + * + * @return A UnixDomainSocketAddress + * + * @throws InvalidPathException + * If the path cannot be converted to a Path + * + * @throws NullPointerException if pathname is {@code null} + */ + public static UnixDomainSocketAddress of(String pathname) { + return of(Path.of(pathname)); + } + + /** + * Create a UnixDomainSocketAddress for the given path. + * + * @param path + * The path to the socket, which can be empty + * + * @return A UnixDomainSocketAddress + * + * @throws IllegalArgumentException + * If the path is not associated with the default file system + * + * @throws NullPointerException if path is {@code null} + */ + public static UnixDomainSocketAddress of(Path path) { + return new UnixDomainSocketAddress(path); + } + + /** + * Return this address's path. + * + * @return this address's path + */ + public Path getPath() { + return path; + } + + /** + * Returns the hash code of this {@code UnixDomainSocketAddress} + */ + @Override + public int hashCode() { + return path.hashCode(); + } + + /** + * Compares this address with another object. + * + * @return true if the path fields are equal + */ + @Override + public boolean equals(Object o) { + if (!(o instanceof UnixDomainSocketAddress)) + return false; + UnixDomainSocketAddress that = (UnixDomainSocketAddress)o; + return this.path.equals(that.path); + } + + /** + * Returns a string representation of this {@code UnixDomainSocketAddress}. + * + * @return this address's path which may be empty for an unnamed address + */ + @Override + public String toString() { + return path.toString(); + } +} diff a/src/java.base/share/classes/java/nio/channels/DatagramChannel.java b/src/java.base/share/classes/java/nio/channels/DatagramChannel.java --- a/src/java.base/share/classes/java/nio/channels/DatagramChannel.java +++ b/src/java.base/share/classes/java/nio/channels/DatagramChannel.java @@ -148,10 +148,13 @@ * * @return A new datagram channel * * @throws IOException * If an I/O error occurs + * + * @see + * java.net.preferIPv4Stack system property */ public static DatagramChannel open() throws IOException { return SelectorProvider.provider().openDatagramChannel(); } @@ -167,10 +170,13 @@ * java.nio.channels.spi.SelectorProvider#openDatagramChannel(ProtocolFamily) * openDatagramChannel} method of the system-wide default {@link * java.nio.channels.spi.SelectorProvider} object. The channel will not be * connected. * + * @apiNote Unix domain sockets + * are not supported by DatagramChannel. + * * @param family * The protocol family * * @return A new datagram channel * @@ -180,10 +186,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 1.7 */ public static DatagramChannel open(ProtocolFamily family) throws IOException { return SelectorProvider.provider().openDatagramChannel(requireNonNull(family)); } @@ -627,7 +636,6 @@ * @throws ClosedChannelException {@inheritDoc} * @throws IOException {@inheritDoc} */ @Override public abstract SocketAddress getLocalAddress() throws IOException; - } diff a/src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java b/src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java --- a/src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java +++ b/src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java @@ -24,31 +24,37 @@ */ 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; /** * A selectable channel for stream-oriented listening sockets. * - *
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; - } diff a/src/java.base/share/classes/java/nio/channels/SocketChannel.java b/src/java.base/share/classes/java/nio/channels/SocketChannel.java --- a/src/java.base/share/classes/java/nio/channels/SocketChannel.java +++ b/src/java.base/share/classes/java/nio/channels/SocketChannel.java @@ -24,51 +24,59 @@ */ 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; import static java.util.Objects.requireNonNull; /** * A selectable channel for stream-oriented connecting sockets. * - *
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. + *
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 Internet protocol 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. * *
Socket channels support non-blocking connection: A socket * channel may be created and the process of establishing the link to the * remote socket may be initiated via the {@link #connect connect} method for * later completion by the {@link #finishConnect finishConnect} method. * Whether or not a connection operation is in progress may be determined by * invoking the {@link #isConnectionPending isConnectionPending} method. * - *
Socket channels support asynchronous shutdown, which is similar + *
Socket channels support asynchronous shutdown, 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 * operation in the blocked thread will complete without reading any bytes and * will return {@code -1}. If the output side of a socket is shut down by one * thread while another thread is blocked in a write operation on the socket's * channel, then the blocked thread will receive an {@link * AsynchronousCloseException}. * *
Socket options are configured using the {@link #setOption(SocketOption,Object) - * setOption} method. Socket channels support the following options: + * setOption} method. Socket channels for Internet protocol sockets support + * following options: *
*- * Additional (implementation specific) options may also be supported. + * + ** * *
*@@ -103,11 +111,40 @@ * * *Disable the Nagle algorithm *
Socket channels for Unix domain sockets support: + *
+ *+ * + *+ * + * + *
+ *+ * + * + * + *Option Name + *Description + *+ * + *{@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} + *The size of the socket send buffer + *+ * + *{@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} + *The size of the socket receive buffer + *+ * + * + *{@link java.net.StandardSocketOptions#SO_LINGER SO_LINGER} + *Linger on close if data is present (when configured in blocking mode + * only) + *
Additional (implementation specific) options may also be supported. * *
Socket channels are safe for use by multiple concurrent threads. They * support concurrent reading and writing, though at most one thread may be * reading and at most one thread may be writing at any given time. The {@link * #connect connect} and {@link #finishConnect finishConnect} methods are @@ -134,21 +171,24 @@ protected SocketChannel(SelectorProvider provider) { super(provider); } /** - * Opens a socket channel. + * Opens a socket channel for an Internet protocol socket. * *
The new channel is created by invoking the {@link * java.nio.channels.spi.SelectorProvider#openSocketChannel * openSocketChannel} method of the system-wide default {@link * java.nio.channels.spi.SelectorProvider} object.
* * @return A new socket channel * * @throws IOException * If an I/O error occurs + * + * @see + * java.net.preferIPv4Stack system property */ public static SocketChannel open() throws IOException { return SelectorProvider.provider().openSocketChannel(); } @@ -172,23 +212,32 @@ * 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 SocketChannel open(ProtocolFamily family) throws IOException { return SelectorProvider.provider().openSocketChannel(requireNonNull(family)); } /** * Opens a socket channel and connects it to a remote address. * - *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.
+ *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. + * + *
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.
* * @param remote * The remote address to which the new channel is to be connected * * @return A new, and connected, socket channel @@ -202,26 +251,37 @@ * while the connect operation is in progress, thereby * closing the channel and setting the current thread's * 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 * * @throws SecurityException * If a security manager has been installed * and it does not permit access to the given remote endpoint * * @throws IOException * If some other I/O error occurs + * + * @see + * java.net.preferIPv4Stack system property */ public static SocketChannel open(SocketAddress remote) throws IOException { - SocketChannel sc = open(); + SocketChannel sc; + 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) { try { sc.close(); @@ -253,21 +313,55 @@ // -- Socket-specific operations -- /** + * Binds the channel's socket to a local address. + * + *This method is used to establish an association between the socket + * and a local address. For Internet Protocol 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 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. If a socket channel to a Unix + * Domain socket is implicitly bound by connecting it without calling + * bind first, then its socket is + * unnamed + * with no corresponding socket file in the file-system. If a socket channel + * to a Unix Domain socket is automatically 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 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 + * 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 * @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 operation + * If a security manager has been installed and its {@link + * 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 */ @Override public abstract SocketChannel bind(SocketAddress local) @@ -327,14 +421,14 @@ public abstract SocketChannel shutdownOutput() throws IOException; /** * Retrieves a socket associated with this channel. * - *
The returned object will not declare any public methods that are not - * declared in the {@link java.net.Socket} class.
- * * @return A socket associated with this channel + * + * @throws UnsupportedOperationException + * If the channel's socket is not an Internet protocol socket */ public abstract Socket socket(); /** * Tells whether or not this channel's network socket is connected. @@ -366,16 +460,23 @@ * *If this channel is in blocking mode then an invocation of this * method will block until the connection is established or an I/O error * occurs. * - *
This method performs exactly the same security checks as the {@link - * java.net.Socket} class. That is, if a security manager has been + *
For channels to Internet protocol 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. * + *
For channels to Unix Domain sockets, this method checks + * {@link java.net.NetPermission NetPermission}{@code + * ("accessUnixDomainSocket")} with the security manager's {@link + * SecurityManager#checkPermission(java.security.Permission) + * checkPermission} method. + * *
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 * invocation is complete. If a connection attempt is initiated but fails, * that is, if an invocation of this method throws a checked exception, @@ -407,11 +508,11 @@ * while the connect operation is in progress, thereby * closing the channel and setting the current thread's * 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 * * @throws SecurityException @@ -475,13 +576,16 @@ public abstract boolean finishConnect() throws IOException; /** * Returns the remote address to which this channel's socket is connected. * - *
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}. + *
Where the channel's socket is bound and connected to an Internet + * Protocol socket address then the return value is of type + * {@link java.net.InetSocketAddress}. + * + *
Where the channel's socket is bound and connected to a Unix Domain + * socket address, the returned address is a {@link UnixDomainSocketAddress}. * * @return The remote address; {@code null} if the channel's socket is not * connected * * @throws ClosedChannelException @@ -537,25 +641,31 @@ return write(srcs, 0, srcs.length); } /** * {@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; - } diff a/src/java.base/share/classes/java/nio/channels/package-info.java b/src/java.base/share/classes/java/nio/channels/package-info.java --- a/src/java.base/share/classes/java/nio/channels/package-info.java +++ b/src/java.base/share/classes/java/nio/channels/package-info.java @@ -239,10 +239,32 @@ * implements unidirectional pipes. In all cases, a new selectable channel is * created by invoking the static {@code open} method of the corresponding class. * If a channel needs an associated socket then a socket will be created as a side * effect of this operation. * + *
{@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}. + * + *
Channels for Internet Protocol sockets are created using the + * {@link java.net.StandardProtocolFamily#INET INET} or {@link + * java.net.StandardProtocolFamily#INET6 INET6} protocol families. Internet + * Protocol 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. Internet Protocol sockets are also the default + * type created, when a protocol family is not specified in the channel factory + * creation method. + * + *
Channels for Unix Domain sockets are created + * using the {@link java.net.StandardProtocolFamily#UNIX UNIX} protocol family. + * Unix Domain 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. + * *
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 * java.nio.channels.spi} package. It is not expected that many developers * will actually make use of this facility; it is provided primarily so that diff a/src/java.base/share/classes/java/nio/channels/spi/SelectorProvider.java b/src/java.base/share/classes/java/nio/channels/spi/SelectorProvider.java --- a/src/java.base/share/classes/java/nio/channels/spi/SelectorProvider.java +++ b/src/java.base/share/classes/java/nio/channels/spi/SelectorProvider.java @@ -266,38 +266,42 @@ * on UNIX systems, the Internet services daemon (inetd) is used to * start programs to service requests when a request arrives on an * associated network port. In this example, the process that is started, * inherits a channel representing a network socket. * - *
In cases where the inherited channel represents a network socket - * then the {@link java.nio.channels.Channel Channel} type returned + *
In cases where the inherited channel is for an Internet protocol + * socket then the {@link Channel Channel} type returned * by this method is determined as follows: * *
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. + *
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. *
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. + *
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. *
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. + *
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. *
In addition to the network-oriented channels described, this method - * may return other kinds of channels in the future. + *
In cases where the inherited channel is for a Unix domain + * socket then the {@link Channel} type returned is the same as for + * Internet protocol sockets as described above, except that + * datagram-oriented sockets are not supported. + * + *
In addition to the two types of socket just described, this method + * may return other types in the future. * *
The first invocation of this method creates the channel that is * returned. Subsequent invocations of this method return the same * channel.
* diff a/src/jdk.net/share/classes/jdk/net/ExtendedSocketOptions.java b/src/jdk.net/share/classes/jdk/net/ExtendedSocketOptions.java --- a/src/jdk.net/share/classes/jdk/net/ExtendedSocketOptions.java +++ b/src/jdk.net/share/classes/jdk/net/ExtendedSocketOptions.java @@ -178,17 +178,38 @@ * @since 15 */ public static final SocketOptionThe value of this socket option is a {@link UnixDomainPrincipal} that + * represents the credentials of a peer connected to a Unix Domain socket. + * The credentials are those that applied at the time the socket was first + * connected or accepted. + * + *
The socket option is read-only and an attempt to set the socket option
+ * will throw {@code SocketException}. {@code SocketException} is also thrown
+ * when attempting to get the value of the socket option on an unconnected Unix
+ * Domain socket.
+ *
+ * @since 16
+ */
+ public static final SocketOption