JDK-8230965 : DnsClient TCP socket timeout
  • Type: CSR
  • Component: core-libs
  • Sub-Component: javax.naming
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 14
  • Submitted: 2019-09-13
  • Updated: 2019-09-21
  • Resolved: 2019-09-20
Related Reports
CSR :  
JDK-8228580 - DnsClient TCP socket timeout
Description
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
      */
Comments
These are not system properties, they are properties defined in the environment properties specified to the InitialDirContext or constructors in the JNDI API to provide configuration. So no systemProperty tag here. The only real changes in this CSR is copying the documentation for these properties into the API docs (they were in the JNDI docs historically) and extending the timeout to TCP connections (the original properties were documented for UDP only).
21-09-2019
If there are system properties, please document them using the systemPropety javadoc tag. Approved conditional on creating a release note for the parent change.
20-09-2019
The `com.sun.jndi.dns.timeout.initial` and `com.sun.jndi.dns.timeout.retries` properties have existed since JDK 1.4. The timeout was originally for UDP only and is extended to TCP here. Including the description in the API docs seems the right approach.
16-09-2019