This repo is no longer actively maintained. While it should continue to work and there are no major known bugs, we will not be improving dns-java or releasing new versions.

This small DNS wrapper library provides some useful pieces of functionality related to SRV lookups.

Sometimes it is useful to default to previously returned, retained values, if a dns lookup should fail or return an empty result. This behavior is controlled by the retainingDataOnFailures() and retentionDurationMillis(long) methods in DnsSrvResolvers.DnsSrvResolverBuilder.

It's often useful to update where you try to connect based on changes in lookup results, and this library provides functionality that allows you to get notified when things change by implementing this interface (defined in the ChangeNotifier interface):

  interface Listener<T> {
    /**
     * Signal that set of records changed.
     *
     * @param changeNotification An object containing details about the change
     */
    void onChange(ChangeNotification<T> changeNotification);
  }
  /**
   * A change event containing the current and previous set of records.
   */
  interface ChangeNotification<T> {
    Set<T> current();
    Set<T> previous();
  }

Take a look at the PollingUsage example for an example.

If you have a statistics system that can be integrated with using the munin protocol, the method metered() in DnsSrvResolvers.DnsSrvResolverBuilder enables this in conjunction with the spotify munin forwarder. Have a look at the BasicUsage example for details on how to set that up.

The entry point to lookups is through an instance of DnsSrvResolver obtained via the DnsSrvResolvers factory class.

To periodically check a set of records and react to changes, use the DnsSrvWatcher interface obtained via the DnsSrvWatchers factory class.

For example code, have a look at BasicUsage example and PollingUsage example

To include the latest released version in your maven project, do:

  <dependency>
    <groupId>com.spotify</groupId>
    <artifactId>dns</artifactId>
    <version>3.2.2</version>
  </dependency>

NOTE: version 3.1.0 is broken; you cannot use the retention feature in that version.

This software is released under the Apache License 2.0. More information in the file LICENSE distributed with this project.