Summary
-------
This CSR proposes to deprecate the API points for statically configuring a system-wide factory for the socket types in the java.net package.
Specifically, the following methods:
- `static void ServerSocket.setSocketFactory���(SocketImplFactory fac)`
- `static void Socket.setSocketImplFactory���(SocketImplFactory fac)`
- `static void DatagramSocket.setDatagramSocketImplFactory���(DatagramSocketImplFactory fac)`
Problem
-------
In early JDK releases, these methods provided a way to replace the system wide implementation of `Socket`, `ServerSocket`, and `DatagramSocket`. However, they have been mostly obsolete since Java 1.4.
Solution
--------
If required, a `Socket`, or `ServerSocket`, can be created to use a custom implementation by extending their corresponding class and using the protected constructor `Socket(SocketImpl)`, or `ServerSocket(SocketImpl)`, that takes a `SocketImpl` implementation as a parameter. The constructor `DatagramSocket(DatagramSocketImpl)` can also be used in similar way for the creation of a `DatagramSocket` with a custom implementation.
Alternatively, `SocketChannel`, `ServerSocketChannel`, or `DatagramChannel` can be used.
Specification
-------------
java/net/Socket.java
/**
* Sets the client socket implementation factory for the
* application. The factory can be specified only once.
* <p>
* When an application creates a new client socket, the socket
* implementation factory's {@code createSocketImpl} method is
* called to create the actual socket implementation.
* <p>
* Passing {@code null} to the method is a no-op unless the factory
* was already set.
* <p>If there is a security manager, this method first calls
* the security manager's {@code checkSetFactory} method
* to ensure the operation is allowed.
* This could result in a SecurityException.
*
* @param fac the desired factory.
* @throws IOException if an I/O error occurs when setting the
* socket factory.
* @throws SocketException if the factory is already defined.
* @throws SecurityException if a security manager exists and its
* {@code checkSetFactory} method doesn't allow the operation.
* @see java.net.SocketImplFactory#createSocketImpl()
* @see SecurityManager#checkSetFactory
+ * @deprecated Use a {@link javax.net.SocketFactory} and subclass {@code Socket}
+ * directly.
+ * <br> This method provided a way in early JDK releases to replace the
+ * system wide implementation of {@code Socket}. It has been mostly
+ * obsolete since Java 1.4. If required, a {@code Socket} can be
+ * created to use a custom implementation by extending {@code Socket}
+ * and using the {@linkplain #Socket(SocketImpl) protected
+ * constructor} that takes an {@linkplain SocketImpl implementation}
+ * as a parameter.
*/
+ @Deprecated(since = "17")
public static synchronized void setSocketImplFactory(SocketImplFactory fac)
java/net/ServerSocket.java
/**
* Sets the server socket implementation factory for the
* application. The factory can be specified only once.
* <p>
* When an application creates a new server socket, the socket
* implementation factory's {@code createSocketImpl} method is
* called to create the actual socket implementation.
* <p>
* Passing {@code null} to the method is a no-op unless the factory
* was already set.
* <p>
* If there is a security manager, this method first calls
* the security manager's {@code checkSetFactory} method
* to ensure the operation is allowed.
* This could result in a SecurityException.
*
* @param fac the desired factory.
* @throws IOException if an I/O error occurs when setting the
* socket factory.
* @throws SocketException if the factory has already been defined.
* @throws SecurityException if a security manager exists and its
* {@code checkSetFactory} method doesn't allow the operation.
* @see java.net.SocketImplFactory#createSocketImpl()
* @see SecurityManager#checkSetFactory
+ * @deprecated Use a {@link javax.net.ServerSocketFactory} and subclass {@code ServerSocket}
+ * directly.
+ * <br> This method provided a way in early JDK releases to replace the
+ * system wide implementation of {@code ServerSocket}. It has been mostly
+ * obsolete since Java 1.4. If required, a {@code ServerSocket} can be
+ * created to use a custom implementation by extending {@code ServerSocket}
+ * and using the {@linkplain #ServerSocket(SocketImpl) protected
+ * constructor} that takes an {@linkplain SocketImpl implementation}
+ * as a parameter.
*/
+ @Deprecated(since = "17")
public static synchronized void setSocketFactory(SocketImplFactory fac) throws IOException {
java/net/DatagramSocket.java
/**
* Sets the datagram socket implementation factory for the
* application. The factory can be specified only once.
* <p>
* When an application creates a new datagram socket, the socket
* implementation factory's {@code createDatagramSocketImpl} method is
* called to create the actual datagram socket implementation.
* <p>
* Passing {@code null} to the method is a no-op unless the factory
* was already set.
*
* <p>If there is a security manager, this method first calls
* the security manager's {@code checkSetFactory} method
* to ensure the operation is allowed.
* This could result in a SecurityException.
*
* @param fac the desired factory.
* @throws IOException if an I/O error occurs when setting the
* datagram socket factory.
* @throws SocketException if the factory is already defined.
* @throws SecurityException if a security manager exists and its
* {@code checkSetFactory} method doesn't allow the operation.
* @see java.net.DatagramSocketImplFactory#createDatagramSocketImpl()
* @see SecurityManager#checkSetFactory
* @since 1.3
*
+ * @deprecated Use {@link DatagramChannel}, or subclass {@code DatagramSocket}
+ * directly.
+ * <br> This method provided a way in early JDK releases to replace the
+ * system wide implementation of {@code DatagramSocket}. It has been mostly
+ * obsolete since Java 1.4. If required, a {@code DatagramSocket} can be
+ * created to use a custom implementation by extending {@code DatagramSocket}
+ * and using the {@linkplain #DatagramSocket(DatagramSocketImpl) protected
+ * constructor} that takes an {@linkplain DatagramSocketImpl implementation}
+ * as a parameter.
*/
+ @Deprecated(since = "17")
public static synchronized void setDatagramSocketImplFactory(DatagramSocketImplFactory fac) throws IOException