Summary

Specify the behavior of timeout-related properties for the JDK DNS Client.

Problem

TCP queries in the DNS Client do not respect timeouts. In particular, they do not respect a timeout setting which is already used with UDP queries, com.sun.jndi.dns.timeout.initial. As a result, users might observe TCP queries hanging indefinitely.

Solution

Update the module documentation to specify that the value of com.sun.jndi.dns.timeout.initial is applied to DNS query regardless of the type of communication attempted.

The com.sun.jndi.dns.timeout.initial property is one of many properties that were described in the JNDI tutorials and guides. Somewhere along the line this type of JNDI documentation was lost and the most recent version that is discoverable on the web seems to reside here: https://docs.oracle.com/javase/8/docs/technotes/guides/jndi/jndi-dns.html. (An earlier version can be seen here: https://download.oracle.com/otn_hosted_doc/jdeveloper/904preview/jdk14doc/docs/guide/jndi/jndi-dns.html.)

It is not the goal of this CSR to bring all the properties from that lost guide to the module documentation. Instead, only com.sun.jndi.dns.timeout.initial and com.sun.jndi.dns.timeout.retries properties are brought. The reason is that the documentation of the former property, com.sun.jndi.dns.timeout.initial, needs to be updated to accommodate the change in the implementation. The latter property, com.sun.jndi.dns.timeout.retries, is also brought because it is naturally linked to the former property through the algorithm described in the guide.

Specifying other properties, if needed, should be addressed in a separate CSR.

Specification

diff --git a/src/jdk.naming.dns/share/classes/module-info.java b/src/jdk.naming.dns/share/classes/module-info.java
--- a/src/jdk.naming.dns/share/classes/module-info.java
+++ b/src/jdk.naming.dns/share/classes/module-info.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,7 +26,38 @@
 /**
  * Provides the implementation of the DNS Java Naming provider.
  *
+ * <h2>Environment Properties</h2>
+ *
+ * <p> The following JNDI environment properties may be used when creating
+ * the initial context.
+ *
+ * <ul>
+ *    <li>com.sun.jndi.dns.timeout.initial</li>
+ *    <li>com.sun.jndi.dns.timeout.retries</li>
+ *  </ul>
+ *
+ * <p> These properties are used to alter the timeout-related defaults that the
+ * DNS provider uses when submitting queries. The DNS provider submits queries
+ * using the following exponential backoff algorithm. The provider submits a
+ * query to a DNS server and waits for a response to arrive within a timeout
+ * period (1 second by default). If it receives no response within the timeout
+ * period, it queries the next server, and so on. If the provider receives no
+ * response from any server, it doubles the timeout period and repeats the
+ * process of submitting the query to each server, up to a maximum number of
+ * retries (4 by default).
+ *
+ * <p> The {@code com.sun.jndi.dns.timeout.initial} property, if set, specifies
+ * the number of milliseconds to use as the initial timeout period (i.e., before
+ * any doubling). If this property has not been set, the default initial timeout
+ * is 1000 milliseconds.
+ *
+ * <p> The {@code com.sun.jndi.dns.timeout.retries} property, if set, specifies
+ * the number of times to retry each server using the exponential backoff
+ * algorithm described previously. If this property has not been set, the
+ * default number of retries is 4.
+ *
  * @provides javax.naming.spi.InitialContextFactory
+ *
  * @moduleGraph
  * @since 9
  */