Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 14
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      low
    • Compatibility Risk Description:
      A timeout is introduced for the TCP-related DNS activities where previously there was none. Users might need to adjust the value of the timeout depending on their environment.
    • Interface Kind:
      System or security property, Use or define an environment variable
    • Scope:
      JDK

      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
        */

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                prappo Pavel Rappo
                Reporter:
                prappo Pavel Rappo
                Reviewed By:
                Alan Bateman, Chris Hegarty
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: