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.hega...@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.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
>>
>
