Here is an initial attempt to document these timeout/retry properties. It’s
effectively the wording lifted from the tech notes [1], with “UDP” removed.
I deliberately avoided describing the implementation. It serves little purpose,
and in fact will greatly complicate the description, as well as constrain the
implementation. I personally dislike parts of the existing implementation (
which I will ignore ), so baking them into the spec would be a mistake.
There are clearly a lot more properties that could be specified, that is far
far beyond the scope of this change.
If we add such documentation, then a CSR ( with JDK-scope ) will be needed.
--- a/src/jdk.naming.dns/share/classes/module-info.java
+++ b/src/jdk.naming.dns/share/classes/module-info.java
@@ -26,7 +26,38 @@
/**
* Provides the implementation of the DNS Java Naming provider.
*
+ * <2>Environment Properties</h2>
+ *
+ * <p> The following JNDI environment properties are relevant to the DNS
+ * provider.
+ *
+ * <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
*/
-Chris.
[1] https://docs.oracle.com/javase/6/docs/technotes/guides/jndi/jndi-dns.html
> On 11 Sep 2019, at 16:55, Alan Bateman <alan.bate...@oracle.com> wrote:
>
> On 11/09/2019 16:16, Pavel Rappo wrote:
>>
>>> On 11 Sep 2019, at 16:10, Alan Bateman <alan.bate...@oracle.com> wrote:
>>>
>>> I assume extending the timeout to TCP will require at least some minimal
>>> updates to the descriptions.
>> Which descriptions do you have in mind? I cannot seem to find that text
>> anywhere in the current repo (jdk/jdk)
> I don't think the jndi-dns docs page is in the jdk repo. Since JDK 9, a good
> place for service providers to document capability and configuration is their
> module description and I think at least some of the documentation from that
> page should move into the jdk.naming.dns module description (that's for
> another issue of course). However, for the changes under discussion here then
> I don't think it's unreasonable to provide an updated description of the
> timeout property.
>
> -Alan
>
