Joala DNS is meant for tests which normally would need to modify the etc/hosts file of your system. It serves as DNS name service.

Usage:

The recommended usage is to set the JVM system property sun.net.spi.nameservice.provider.1 to the Joala DNS identifier dns,joala (type and provider name). This will allow to override hostnames before they are looked up for the first time.

In order to be able to redefine a hostname at runtime you have to disable caching as described in {@link java.net.InetAddress} which is to set the JVM security properties networkaddress.cache.ttl and networkaddress.cache.negative.ttl to 0 (zero). To do so add the following entries to a file for example named .java.joala.dns.security in your user home folder: 

  // Disable caching to be able to remap when using Joala DNS.
  // This is the officially supported way for Java - while Joala DNS tries
  // its best effort via reflection that you don't need to do that.
  //
  // Usage:
  // * Copy for example to your user.home-folder
  // * Start your JVM with -Djava.security.properties=<user-home>/.java.joala.dns.security
  //
  networkaddress.cache.ttl=0
  networkaddress.cache.negative.ttl=0

Having this the complete command line to add to your Java call is: 

  -Dsun.net.spi.nameservice.provider.1=dns,joala \
  -Djava.security.properties=<user-home>/.java.joala.dns.policy

Fallback Strategies:

Joala DNS has two implemented fallback strategies if it cannot resolve a hostname. You can specify them at command line with their IDs by setting the system property net.joala.dns.fallbacks. The default value is dnsjava,default. Any other value is ignored. Thus if you state for example an empty string or disabled no fallback strategies will be applied.

If you are Java 7...

Since Java 7 these fallback strategies are not really necessary anymore as the Name Service lookup strategy implemented in {@link java.net.InetAddress} has changed from a single name service to a list of nameservices which you can give an order. Thus having this, your provider properties could look like this: 

  -Dsun.net.spi.nameservice.provider.1=dns,joala \
  -Dsun.net.spi.nameservice.provider.2=dns,dnsjava \
  -Dsun.net.spi.nameservice.provider.3=default

Which tells: Use Joala DNS first, if it fails to resolve a host, use DNS Java and eventually fallback to the default JVM implementation.

Debugging:

Joala DNS must not use any well known logging framework. This is because most of them require a DNS server to parse their XML configurations and such. That's why Joala DNS uses a comparable approach like DNS Java which is to use the System-PrintStreams err and out for reporting. By default all messages are disabled. Joala DNS honors the same settings like DNS Java to enable reporting. The easiest way to provide this at the command line: 

  -Ddnsjava.options=verbose

If you want to do that in from your Java code, then add this call: 

  org.xbill.DNS.Options.set("verbose");

References:

@since 10/6/12