JEP 373: Reimplement the Legacy DatagramSocket API

OwnerDaniel Fuchs
StatusClosed / Delivered
Componentcore-libs /
Discussionnet dash dev at openjdk dot java dot net
Reviewed byAlan Bateman, Brian Goetz, Chris Hegarty
Endorsed byBrian Goetz
Created2019/12/10 16:13
Updated2023/03/04 02:10


Replace the underlying implementations of the and APIs with simpler and more modern implementations that are easy to maintain and debug. The new implementations will be easy to adapt to work with virtual threads, currently being explored in Project Loom. This is a follow-on to JEP 353, which already reimplemented the legacy Socket API.


The code base of the and APIs, and their underlying implementations, is old and brittle:

In addition, in the context of virtual threads that park rather than block underlying kernel threads in system calls, the current implementation is not fit for purpose. As datagram-based transports gain traction again (e.g. QUIC), a simpler and more maintainable implementation is needed.


Currently, the DatagramSocket and MulticastSocket classes delegate all socket calls to a implementation, for which different platform-specific concrete implementations exist: PlainDatagramSocketImpl on Unix platforms, and TwoStackPlainDatagramSocketImpl and DualPlainDatagramSocketImpl on Windows platforms. The abstract DatagramSocketImpl class, which dates back to JDK 1.1, is very under-specified and contains several obsolete methods that are an impediment to providing an implementation of this class based on NIO (see alternatives, discussed below).

Rather than provide a drop-in replacement for implementations of DatagramSocketImpl, similar to what was done in JEP 353 for SocketImpl, this JEP proposes to make DatagramSocket internally wrap another instance of DatagramSocket to which it delegates all calls directly. The wrapped instance is either a socket adapter created from a NIO DatagramChannel::socket (the new implementation), or else a clone of the legacy DatagramSocket class which then delegates to the legacy DatagramSocketImpl implementation (for the purpose of implementing a backward compatibility switch). If a DatagramSocketImplFactory is installed by an application, the old legacy implementation is selected. Otherwise, the new implementation is selected and used by default.

To reduce the risk of switching the implementation after more than twenty years, the legacy implementation will not be removed. A JDK-specific system property,, is introduced to configure the JDK to use the legacy implementation (see risks and assumptions, below). If set with no value or set to the value ”true" at startup, the legacy implementation is used. Otherwise, the new (NIO-based) implementation is used. In some future release we will remove the legacy implementation and the system property. At some point we may also deprecate and remove DatagramSocketImpl and DatagramSocketImplFactory.

The new implementation is enabled by default. It provides non-interruptible behavior for datagram and multicast sockets by directly using the platform-default implementation of the selector provider ( and Installing a custom selector provider will thus have no effect on DatagramSocket and MulticastSocket.


We investigated, prototyped, and discarded two alternative approaches.

Alternative 1

Create an implementation of DatagramSocketImpl that delegates all its calls to a wrapped DatagramChannel and Upgrade to extend

This approach showed that it would be relatively easy to provide an implementation of DatagramSocketImpl based on DatagramChannel. Tests were passing, but it also highlighted several limitations:

Alternative 2

Create an implementation of DatagramSocketImpl in the package that invokes low-level primitives. This allowed the implementation to directly access lower-level NIO primitives instead of relying on DatagramChannel. This was somewhat analogous to what was done for reimplementing Socket and ServerSocket in JEP 353.


The existing tests in the jdk/jdk repository will be used to test the new implementation. To ensure a smooth transition, the new implementation should pass the tier2 (jdk_net and jdk_nio) regression-test suite and the JCK for java_net/api. The jdk_net test group has accumulated many tests for networking corner case scenarios over the years. Some of the tests in this test group will be modified to run twice, the second time with to ensure that the old implementation does not decay during the time that the JDK includes both implementations. New tests will be added as required, to expand code coverage and increase confidence in the new implementation.

Every effort will be made to publicize the proposal and encourage developers that have code using DatagramSocket and MulticastSocket to test their code with the early-access builds that are published on

The microbenchmarks in the jdk/jdk repository include benchmarks for DatagramChannel. Similar benchmarks for datagram socket will be created if missing, or updated if they already exist, in a way that makes it easy to compare the old and new implementations.

Risks and Assumptions

The primary risk of this proposal is that there is existing code that depends upon unspecified behavior in corner cases where the old and new implementations behave differently. To minimize this risk, some preparatory work to clarify the specifications of DatagramSocket and MulticastSocket, and to minimize the behavioral differences between these classes and the DatagramChannel::socket adapter, has already been done in JDK 14 and JDK 15. Some small differences, listed below, might however persist. These differences might be observable in corner-case situations but should be transparent to the vast majority of API users. The differences we have identified so far are listed here; all but the first two can be mitigated by running with either or

Other observable behavioral differences:

Aside from behavioral differences, the performance of the new implementation may differ compared to the old when running certain workloads. This JEP will endeavor to provide some performance benchmarks to gauge the difference.