java-dns-cache-manipulator lets a JVM answer DNS for you

It manipulates the JVM's cache, not the machine's resolver

The project description sets out the scope in one sentence. DCM is a tiny, zero dependency, thread safe Java library for setting and viewing DNS programmatically without touching the host file, which makes unit and integration testing portable, and it also includes a tiny tool for setting and viewing the DNS of running JVM processes. That last clause is the important design constraint and the interesting capability. The library does not rewrite `/etc/hosts` and does not ask you to run a local DNS server, so a test that needs `api.example.internal` to resolve to `127.0.0.1` can arrange that in the process it is running in, and the same test suite can be pointed at a real environment by changing nothing. The tool exists for the case where you cannot control the process, so it reaches into a JVM that is already running, which is what you need when the DNS cache is the problem and the code under test is not yours.

The library's operations are a small, complete set

The feature list for the library is short enough to read twice, and the order of the items is the order of a workflow. You can set or reset a DNS cache entry, and once you do the JVM will not look DNS up again, and you can do that for a single DNS record or in batch through a properties file. You can view the content of a DNS cache entry, and the documentation is careful to say that this covers the positive cache and the negative cache. You can remove a DNS cache entry, which makes the JVM look that name up again. You can clear the whole cache, which re-looks up every domain name. And you can set or view the default DNS cache time of the JVM, again for both the positive and the negative side. The split between positive and negative caching is the detail that matters most in practice, because a negative entry means the name failed to resolve and a JVM that has cached that failure will not try again, which is exactly the kind of behaviour that makes a test flaky after the first run.

Batch configuration is a properties file

The user guide lists the ways of using the library, and the second is the one that scales. A single entry can be set directly in code, which is fine for a test that needs one name, and a batch of them can be configured through a `dns-cache.properties` file, which is the form you want when a test suite depends on a whole set of names resolving to local addresses. The file is a properties file rather than a bespoke format, which means it can be generated by a build step, passed as a system property or written by a fixture, and it does not need its own parser. The same guide then covers viewing the JVM DNS cache, removing an entry, clearing the cache and reading or setting the default cache time, so the operations available in code and the operations available to an operator are the same list.

Three precautions, and the one that surprises people

There is a precautions section for use, and it is worth reading before you file a bug. The first entry concerns JVM settings for Java 16 and later, which implies that the library needs particular flags to be able to do what it does in newer runtimes. The second is domain name case, which follows from the JVM's own behaviour, since the resolver cache is keyed by name and names are case insensitive in some contexts and not in others, so a lookup of `Example.com` and a lookup of `example.com` can end up as two entries or one depending on the runtime. The third is domain resolution cache, which is the point of the whole library, the JVM's own default cache lifetime, and which is why the library also lets you set and view that default. A library that hands you the cache also has to tell you that the cache is the thing it is manipulating, and these three entries are it doing that.

The tool reaches into a JVM you do not control

The second subproject is the tool, and its feature list is the same set of operations with one addition. You can download it, and the release assets include a `dcm-1.8.3.tar.gz` archive. Then you can set or reset a DNS cache entry, view the content of an entry, remove one, clear the cache, and set or view the DNS cache time of the JVM, all against a process that is already running. The extra capability is loading cache entries from a file, and manipulating the cache with a command line option at JVM startup, which is the version that works when the process has not started yet. That combination is what makes the tool useful in practice, since an operator investigating a resolution problem in a running service can set an entry and watch what changes, and a developer can bake the entries into the launch options of a service they are starting.

What the project is actually for

The requirement scenario in the documentation is about making tests portable, and the whole feature set is a consequence of that. Without this library, a test that depends on a name resolving to a local address has three bad options: change the host file, which is shared state that leaks between tests and between developers, stand up a DNS server, which is a service to run in CI, or hope the name resolves, which is not a test. DCM replaces all three with a per process setting. The zero dependency claim matters here, because a test utility that drags a DNS client library into your build is a nuisance, and the thread safety claim matters because a test runner may be running tests in parallel inside one JVM. The tool exists for the neighbouring case, where the code under test is a service you did not write and its resolution is not what you expected.

Versioning, Java support and the build

The release history shows a project that tracks the Java versions it supports rather than ignoring them. v1.8.2 was published in June 2024 with the note that it supports Java 21, v1.8.3 followed in September 2024, and v1.8.4-Alpha1 arrived in May 2026 with support for Java 25, still in alpha. There is also a compatibility note for people on older runtimes, that starting from DCM 1.7 the project moved up to Java 8, and that if you need Java 6 support you should stay on the 1.6.x line. The build is Maven, with the wrapper checked in as `mvnw` and `mvnw.cmd`, and the repository has separate workflows for a fast build and a strong build, with a codecov badge for coverage and published Javadocs. The library is published to Maven Central under the `com.alibaba` group with the artifact `dns-cache-manipulator`, and the licence is Apache-2.0. The last push to the repository was on 2026-08-27.

Editorial conclusion

java-dns-cache-manipulator suits a Java team whose tests depend on a specific name resolving to a specific address, since it removes the need to edit the host's resolver configuration or to depend on a DNS server the test owns. It is a poor fit if you need to influence resolution outside the JVM, since by design it does not touch the host file, and it is a poor fit if you are on an old JVM, since the current line targets Java 8 to 21 with a Java 25 build in an alpha release and the Java 6 support lives in the 1.6.x branch. Before you adopt it, check three things: whether the JVM you run in is covered by the version you pin, since the release notes pair releases with specific Java versions, how your CI image is configured, because the documentation has a precautions section specifically about JVM settings for Java 16 and later, and whether the positive and negative cache semantics match your test expectations, since the library distinguishes them explicitly.

Frequently asked questions

Official sources

1. alibaba/java-dns-cache-manipulator on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases