RFR(s): 8228580: DnsClient TCP socket timeout

[Pavel Rappo]

I like the wording, it's concise. Thanks a lot for helping us with this, Chris!

Trivially, there's a typo: <2> instead of <h2>.

> On 12 Sep 2019, at 12:41, Chris Hegarty <chris.hegarty at oracle.com> wrote:
> 
> 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.Bateman at oracle.com> wrote:
>> 
>> On 11/09/2019 16:16, Pavel Rappo wrote:
>>> 
>>>> On 11 Sep 2019, at 16:10, Alan Bateman <Alan.Bateman at 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
>> 
>