Skip to content

Commit b1955a3

Browse files
oldratleeoldratlee
committed
docs: add English README
1 parent 77faad6 commit b1955a3

File tree

3 files changed

+463
-2
lines changed

3 files changed

+463
-2
lines changed

‎README.md‎

Lines changed: 379 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,379 @@
1+
# <div align="center"><a href="#dummy"><img src="docs/logo-red.png" alt="🌏 Java Dns Cache Manipulator(DCM)"></a></div>
2+
3+
<p align="center">
4+
<a href="https://ci.appveyor.com/project/oldratlee/java-dns-cache-manipulator"><img src="https://img.shields.io/appveyor/ci/oldratlee/java-dns-cache-manipulator/master?logo=appveyor&amp;logoColor=white" alt="Build Status"></a>
5+
<a href="https://coveralls.io/github/alibaba/java-dns-cache-manipulator?branch=master"><img src="https://img.shields.io/coveralls/github/alibaba/java-dns-cache-manipulator/master?logo=coveralls&amp;logoColor=white" alt="Coveralls branch"></a>
6+
<a href="https://codeclimate.com/github/alibaba/java-dns-cache-manipulator/maintainability"><img src="https://api.codeclimate.com/v1/badges/80e64dc9160cf6f62080/maintainability" alt="Maintainability"></a>
7+
<a href="https://openjdk.java.net/"><img src="https://img.shields.io/badge/Java-6+-green?logo=java&amp;logoColor=white" alt="Java support"></a>
8+
<a href="https://www.apache.org/licenses/LICENSE-2.0.html"><img src="https://img.shields.io/github/license/alibaba/java-dns-cache-manipulator?color=4D7A97" alt="License"></a>
9+
<a href="https://alibaba.github.io/java-dns-cache-manipulator/apidocs/"><img src="https://img.shields.io/github/release/alibaba/java-dns-cache-manipulator?label=javadoc&amp;color=3d7c47&amp;logo=microsoft-academic&amp;logoColor=white" alt="Javadocs"></a>
10+
<a href="https://search.maven.org/artifact/com.alibaba/dns-cache-manipulator"><img src="https://img.shields.io/maven-central/v/com.alibaba/dns-cache-manipulator?color=2d545e&amp;logo=apache-maven&amp;logoColor=white" alt="Maven Central"></a>
11+
<a href="https://github.com/alibaba/java-dns-cache-manipulator/releases"><img src="https://img.shields.io/github/release/alibaba/java-dns-cache-manipulator.svg" alt="GitHub release"></a>
12+
<a href="https://gitter.im/alibaba/java-dns-cache-manipulator?utm_source=badge&amp;utm_medium=badge&amp;utm_campaign=pr-badge&amp;utm_content=badge"><img src="https://img.shields.io/gitter/room/alibaba/java-dns-cache-manipulator?color=46BC99&amp;logo=gitter&amp;logoColor=white" alt="Chat at gitter.im"></a>
13+
<a href="https://github.com/alibaba/java-dns-cache-manipulator/stargazers"><img src="https://img.shields.io/github/stars/alibaba/java-dns-cache-manipulator" alt="GitHub Stars"></a>
14+
<a href="https://github.com/alibaba/java-dns-cache-manipulator/fork"><img src="https://img.shields.io/github/forks/alibaba/java-dns-cache-manipulator" alt="GitHub Forks"></a>
15+
<a href="https://github.com/alibaba/java-dns-cache-manipulator/network/dependents"><img src="https://badgen.net/github/dependents-repo/alibaba/java-dns-cache-manipulator?label=user%20repos" alt="user repos"></a>
16+
<a href="https://github.com/alibaba/java-dns-cache-manipulator/issues"><img src="https://img.shields.io/github/issues/alibaba/java-dns-cache-manipulator" alt="GitHub issues"></a>
17+
<a href="https://github.com/alibaba/java-dns-cache-manipulator/graphs/contributors"><img src="https://img.shields.io/github/contributors/alibaba/java-dns-cache-manipulator" alt="GitHub Contributors"></a>
18+
<a href="https://github.com/alibaba/java-dns-cache-manipulator"><img src="https://img.shields.io/github/repo-size/alibaba/java-dns-cache-manipulator" alt="GitHub repo size"></a>
19+
<a href="https://github.com/alibaba/java-dns-cache-manipulator/releases/download/v1.6.3/dcm-1.6.3.tar.gz"><img src="https://img.shields.io/github/downloads/alibaba/java-dns-cache-manipulator/v1.6.3/dcm-1.6.3.tar.gz.svg" alt="GitHub release download - dcm.tar.gz)"></a>
20+
</p>
21+
22+
Java Dns Cache Manipulator(`DCM`) contains 2 subprojects:
23+
24+
- [**`DCM` Library**](library)
25+
A simple 0-dependency thread-safe lib for setting/viewing dns programmatically without touching host file, make unit/integration test portable. Support `Java 6/8/11/17`, support `IPv6`.
26+
- [**`DCM` Tool**](tool)
27+
A tool for setting/viewing dns of running JVM processes.
28+
29+
----------------------------------------
30+
31+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
32+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
33+
34+
- [Java Dns Cache Manipulator(`DCM`) Library](#java-dns-cache-manipulatordcm-library)
35+
- [🔧 Features](#-features)
36+
- [🎨 Requirement Scenario](#-requirement-scenario)
37+
- [👥 User Guide](#-user-guide)
38+
- [Set directly](#set-directly)
39+
- [Batch configuration through the `dns-cache.properties` file](#batch-configuration-through-the-dns-cacheproperties-file)
40+
- [View JVM DNS cache](#view-jvm-dns-cache)
41+
- [Delete a DNS cache](#delete-a-dns-cache)
42+
- [Clear JVM DNS cache](#clear-jvm-dns-cache)
43+
- [Set/View the default DNS cache time of JVM](#setview-the-default-dns-cache-time-of-jvm)
44+
- [Precautions for use](#precautions-for-use)
45+
- [More detailed functions](#more-detailed-functions)
46+
- [🔌 Java API Docs](#-java-api-docs)
47+
- [🍪 Dependency](#-dependency)
48+
- [🗿 More Documentation](#-more-documentation)
49+
- [📚 Related Resources](#-related-resources)
50+
- [Java Dns Cache Manipulator Tool](#java-dns-cache-manipulator-tool)
51+
- [🔧 Features](#-features-1)
52+
- [👥 User Guide](#-user-guide-1)
53+
- [Download](#download)
54+
- [Set/reset DNS](#setreset-dns)
55+
- [View DNS Cache content](#view-dns-cache-content)
56+
- [Delete/Empty DNS Cache](#deleteempty-dns-cache)
57+
- [Set/View JVM's default DNS cache time](#setview-jvms-default-dns-cache-time)
58+
- [📚 Related information](#-related-information)
59+
60+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
61+
62+
----------------------------------------
63+
64+
# Java Dns Cache Manipulator(`DCM`) Library
65+
66+
## 🔧 Features
67+
68+
- Set/reset a DNS cache entry (won't lookup DNS afterwards)
69+
- set a single `DNS` record
70+
- or batch setting through a `Properties` file
71+
- View DNS cache entry content (positive dns cache and/or negative dns cache)
72+
- Delete a DNS cache entry (ie lookup DNS again)
73+
- Clear the DNS Cache (re-Lookup DNS for all domain names)
74+
- Set/View DNS cache time of `JVM` (positive dns cache and negative dns cache)
75+
76+
## 🎨 Requirement Scenario
77+
78+
1. The domain name is hard-coded in some libraries, and have to modify the `host file` binding to do the test(eg. unit test, integration test). Turn out:
79+
- Generally, developers do not have the permission to modify the `host file` on the continuous integration machine, which leads to the continuous integration of the project fail.
80+
- In fact, because of this, the demand for this library was born. 😣 🔫
81+
- Unit testing requires each developer to do some host binding on the development machine, which increases configuration operations and is tedious and repetitive.
82+
2. Some functions require domain names instead of IPs as input parameters, such as HTTP gateways or web applications with domain name restrictions.
83+
- In this case, you need a domain name to connect to the IP of the test machine; Or need use a test domain name that does not exist yet, but you do not want to or can not configure the DNS.
84+
3. In the performance test,
85+
- want to skip lookup DNS through network (bypass the DNS resolution consumption), so that stress testing pays more attention to server response, and stress testing can fully reflects the performance of the core implementation code.
86+
- DNS cache can be set dynamically instead of inflexible ways such as modifying host files and http links.
87+
- A `JVM` process can have a set of domain name binding without affecting other JVM, be able to run stress testing with multi-scenario and multi-domain binding.
88+
4. When opening the `SecurityManager` in `Java` (such as a web application in the Web container `Tomcat`), `Java`'s DNS will not be expired by default. If the IP bound to the domain name changes, you can reset the DNS through this library.
89+
- Set the running JVM DNS Cache through the `DCM` Tool.
90+
application **need not** contain `DCM` Library dependency (ie. `Jar`).
91+
- Or call the method of `DCM` Library through the execution entry, such as remote call or [`jvm-ssh-groovy-shell`](https://github.com/palominolabs/jvm-ssh-groovy-shell).
92+
The application **need** contain `DCM` Library dependency (ie `Jar`).
93+
94+
## 👥 User Guide
95+
96+
Set/View DNS through the class [`DnsCacheManipulator`](src/main/java/com/alibaba/dcm/DnsCacheManipulator.java).
97+
98+
### Set directly
99+
100+
```java
101+
DnsCacheManipulator.setDnsCache("hello.com", "192.168.1.1");
102+
// support IPv6
103+
DnsCacheManipulator.setDnsCache("world.com", "1234:5678:0:0:0:0:0:200e");
104+
105+
// The above settings take effect globally, and then all the domain name resolution logic in Java will be the IP set above.
106+
// Let's use a simple method to get the IP corresponding to the domain name to demonstrate:
107+
108+
String ip = InetAddress.getByName("hello.com").getHostAddress();
109+
// ip = "192.168.1.1"
110+
String ipv6 = InetAddress.getByName("world.com").getHostAddress();
111+
// ipv6 = "1234:5678:0:0:0:0:0:200e"
112+
113+
114+
// set multiple IP
115+
DnsCacheManipulator.setDnsCache("hello-world.com", "192.168.2.1", "192.168.2.2");
116+
117+
String ipHw = InetAddress.getByName("hello-world.com").getHostAddress();
118+
// ipHw = 192.168.2.1, read the first IP
119+
InetAddress[] allIps = InetAddress.getAllByName("hello-world.com");
120+
// Read the multiple IP setting
121+
InetAddress[] allIps = InetAddress.getAllByName("hello-world.com");
122+
123+
124+
// Set the expiration time, unit is milliseconds
125+
DnsCacheManipulator.setDnsCache(3600 * 1000, "hello-hell.com", "192.168.1.1", "192.168.1.2");
126+
```
127+
128+
### Batch configuration through the `dns-cache.properties` file
129+
130+
In testing, it is expected that the domain name binding will be written in a configuration file.
131+
132+
The usage is as follows:
133+
134+
provide the file `dns-cache.properties` on ClassPath:
135+
136+
```bash
137+
# Configuration format:
138+
# <host> = <ip>
139+
hello-world.com=192.168.1.1
140+
# Support setting multiple IPs, separated by commas
141+
foo.com=192.168.1.2,192.168.1.3
142+
# Support IPv6
143+
bar.com=1234:5678:0:0:0:0:0:200e
144+
```
145+
146+
> NOTE:
147+
>
148+
> The default configuration file name is `dns-cache.properties`.
149+
> and the configuration file name used can be modified through the `-D` option `dcm.config.filename` of the `JVM`: `-Ddcm.config.filename=my-dns-cache.properties`.
150+
151+
Then complete the batch setting with the following line of code:
152+
153+
```java
154+
DnsCacheManipulator.loadDnsCacheConfig();
155+
156+
// or load the batch setting from the specified file name
157+
DnsCacheManipulator.loadDnsCacheConfig("my-dns-cache.properties");
158+
```
159+
160+
In unit testing, it is often written in the `setUp` method of the test class, such as:
161+
162+
```java
163+
@BeforeClass
164+
public static void beforeClass() throws Exception {
165+
DnsCacheManipulator.loadDnsCacheConfig();
166+
}
167+
```
168+
169+
### View JVM DNS cache
170+
171+
```java
172+
// Get a dns cache entry by host
173+
DnsCacheEntry entry = DnsCacheManipulator.getDnsCache();
174+
175+
// get whole dns cache info DnsCache including cache and negative cache.
176+
DnsCache dnsCache = DnsCacheManipulator.getWholeDnsCache();
177+
178+
// get positive dns cache entries
179+
// same as DnsCacheManipulator.getWholeDnsCache().getCache()
180+
List<DnsCacheEntry> positiveEntries = DnsCacheManipulator.getWholeDnsCache();
181+
182+
// get dns negative cache entries
183+
// same as DnsCacheManipulator.getWholeDnsCache().getNegativeCache()
184+
List<DnsCacheEntry> positiveEntries = DnsCacheManipulator.getWholeDnsCache();
185+
```
186+
187+
### Delete a DNS cache
188+
189+
aka. relookup DNS later.
190+
191+
```java
192+
DnsCacheManipulator.removeDnsCache("bing.com");
193+
```
194+
195+
### Clear JVM DNS cache
196+
197+
```java
198+
DnsCacheManipulator.clearDnsCache();
199+
```
200+
201+
### Set/View the default DNS cache time of JVM
202+
203+
```java
204+
// View the cache time, in seconds. -1 means always cache, 0 means never cache
205+
int cachePolicy = DnsCacheManipulator.getDnsCachePolicy();
206+
// Set the cache time
207+
DnsCacheManipulator.setDnsCachePolicy(2);
208+
209+
// View the cache time of missed entries(negative entries)
210+
DnsCacheManipulator.getDnsNegativeCachePolicy()
211+
// Set the cache time of missed entries
212+
DnsCacheManipulator.setDnsNegativeCachePolicy(0);
213+
```
214+
215+
### Precautions for use
216+
217+
- The domain name is not case-sensitive, and the domain name will be converted to lower case uniformly before entering the DNS Cache.
218+
One of the causes is that the case of the domain name in the DNS query result will be different from the case of the entered domain name, if the entered domain name has uppercase letters.
219+
- For the logic that has been resolved and saved the IP, setting the JVM DNS cache will not take effect! The connection can be re-created or the Client can be resolved.
220+
For HttpClient:
221+
222+
```java
223+
HttpClient client = new HttpClient();
224+
GetMethod m1 = new GetMethod("https://bing.com");
225+
client.executeMethod(m1);
226+
String content = m1.getResponseBodyAsString();
227+
228+
// Set up DNS and bind to your own machine
229+
DnsCacheManipulator.setDnsCache("bing.com", "192.168.1.1");
230+
231+
// Re-execute m1, still the old result
232+
client.executeMethod(m1);
233+
String content = m1.getResponseBodyAsString();
234+
235+
// Re-create GetMethod to get the results on your own machine
236+
GetMethod m2 = new GetMethod("https://bing.com");
237+
client.executeMethod(m2);
238+
content = m2.getResponseBodyAsString();
239+
```
240+
241+
### More detailed functions
242+
243+
See the documentation for the class [`DnsCacheManipulator`](library/src/main/java/com/alibaba/dcm/DnsCacheManipulator.java).
244+
245+
## 🔌 Java API Docs
246+
247+
Java API document: <http://alibaba.github.io/java-dns-cache-manipulator/apidocs>
248+
249+
## 🍪 Dependency
250+
251+
`Maven` example:
252+
253+
```xml
254+
<dependency>
255+
<groupId>com.alibaba</groupId>
256+
<artifactId>dns-cache-manipulator</artifactId>
257+
<version>1.6.3</version>
258+
</dependency>
259+
```
260+
261+
You can view the latest version at [search.maven.org](https://search.maven.org/artifact/com.alibaba/dns-cache-manipulator).
262+
263+
## 🗿 More Documentation
264+
265+
- [🎓 Developer Guide](docs/developer-guide.md)
266+
267+
## 📚 Related Resources
268+
269+
- Article [Source code analysis of java dns parsing cache / `java dns`解析缓存之源码解析](http://rongmayisheng.com/?p=1006) is very complete and have source code analysis, give noteworthy conclusions:
270+
- Open the SecurityManager in Java, the DNS cache will not be invalidated.
271+
- Otherwise, the accessible DNS resolution will be cached for 30 seconds by default, and the inaccessible DNS resolution will be cached for 10 seconds by default.
272+
- [Regarding the jvm dns cache (domain name cache time) / 关于`jvm dns cache`(域名缓存时间)](https://nigelzeng.iteye.com/blog/1704052), the conclusion of "what strategy is used to return IP for multiple A records" is given:
273+
- During the validity period of the cache, the obtained IP is always the first of all A records in the cache, and there is no such strategy as round robin.
274+
- After the cache is invalidated, perform DNS resolution again. Because the order of the A records returned by the domain name resolution will change (visible in the dig google.com test), the order of the data in the cache has also changed, and the obtained IP will also change.
275+
- [Modify the content of DNS cache in JDK 1.6 through JAVA reflection / 通过`JAVA`反射修改`JDK 1.6`当中`DNS`缓存内容](https://tuicool.com/articles/auYzui), give the scene of setting DNS cache in performance test.
276+
- [The dns cache problem of java InetAddress / java InetAddress 的 dns cache 问题](http://blogjava.net/jjwwhmm/archive/2008/07/09/213685.html) indicates that `HttpClient` needs to recreate the `GetMethod`/`PostMethod` object to make the DNS setting take effect.
277+
278+
# Java Dns Cache Manipulator Tool
279+
280+
## 🔧 Features
281+
282+
- Set/reset a DNS cache entry
283+
- View DNS cache entry content
284+
- Delete a DNS Cache
285+
- Clear DNS Cache
286+
- Set/View DNS cache time of `JVM`
287+
288+
## 👥 User Guide
289+
290+
### Download
291+
292+
[![GitHub release download - dcm.tar.gz)](https://img.shields.io/github/downloads/alibaba/java-dns-cache-manipulator/v1.6.3/dcm-1.6.3.tar.gz.svg)](https://github.com/alibaba/java-dns-cache-manipulator/releases/download/v1.6.3/dcm-1.6.3.tar.gz) download the file `dcm-x.x.x.tar.gz`.
293+
294+
After decompression, run `dcm` in the `bin` directory.
295+
296+
```bash
297+
$ dcm -h
298+
usage: Options
299+
-h,--help show help
300+
-p,--pid <arg> java process id to attach
301+
```
302+
303+
### Set/reset a DNS cache entry
304+
305+
```bash
306+
# For the Java process whose process ID is 12345
307+
# set the domain name foo.com IP to 1.1.1.1
308+
$ dcm -p 12345 set foo.com 1.1.1.1
309+
# For the Java process whose process ID is 12345
310+
# set the domain name bar.com IP to 2.2.2.2 3.3.3.3 (multiple IPs are possible)
311+
$ dcm -p 12345 set bar.com 2.2.2.2 3.3.3.3
312+
```
313+
314+
### View DNS cache entry content
315+
316+
View single entry:
317+
318+
```bash
319+
# For the Java process whose process ID is 12345,
320+
# obtain the DNS entry information of the domain name bing.com
321+
$ dcm -p 12345 get bing.com
322+
bing.com 220.181.57.217,180.149.132.47,123.125.114.144 2015-06-05T18:56:09.635+0800
323+
# The output format:
324+
# "the domain name" "IP list (there may be multiple IPs)" "expiration time"
325+
```
326+
327+
View all DNS cache:
328+
329+
```bash
330+
$ dcm -p 12345 list
331+
Dns cache:
332+
bar.com 2.2.2.2,3.3.3.3 292278994-08-17T15:12:55.807+0800
333+
bing.com 220.181.57.217,180.149.132.47,123.125.114.144 2015-06-05T19:00:30.514+0800
334+
foo.com 1.1.1.1 292278994-08-17T15:12:55.807+0800
335+
Dns negative cache:
336+
# Output entries containing Cache and Negative Cache.
337+
# The entry is indented 4 spaces.
338+
# In the above example, Negative Cache is empty.
339+
```
340+
341+
### Delete a DNS Cache
342+
343+
```bash
344+
# Delete a DNS
345+
$ dcm -p 12345 rm bing.com
346+
```
347+
348+
### Clear DNS Cache
349+
350+
```bash
351+
# Clear all DNS Cache
352+
$ dcm -p 12345 clear
353+
```
354+
355+
### Set/View DNS cache time of `JVM`
356+
357+
```bash
358+
# View the cache time, in seconds.
359+
# -1 means always cache, 0 means no cache
360+
# 查看缓存时间，单位秒。-1表示永远缓存，0表示不缓存
361+
$ dcm -p 12345 getPolicy
362+
30
363+
# Set cache time
364+
$ dcm --pid 12345 setPolicy 5
365+
# View the cache time of missed entries, in seconds.
366+
# -1 means always cache, 0 means no cache
367+
$ dcm -p 12345 getNegativePolicy
368+
10
369+
# Set the cache time of missed entries
370+
# Set the cache time of missed entries
371+
$ dcm -p 12345 setNegativePolicy 0
372+
```
373+
374+
## 📚 Related information
375+
376+
* [Java Agent Specification](http://docs.oracle.com/javase/7/docs/api/java/lang/instrument/package-summary.html)
377+
* [New Features of Java SE 6: New Features of Instrumentation](http://www.ibm.com/developerworks/cn/java/j-lo-jse61/)
378+
* [Creation, dynamic loading and instrumentation with javaagents](http://dhruba.name/2010/02/07/creation-dynamic-loading-and-instrumentation-with-javaagents/)
379+
* [Analysis of JavaAgent loading mechanism](http://nijiaben.iteye.com/blog/1847212)

0 commit comments

Comments
 (0)