Summary

Document two environment properties controlling timeouts in the default JDK implementation of the JNDI LDAP Naming Service Provider. No changes from JDK 16, CSR JDK-8248866.

Problem

The default implementation of the JNDI LDAP Naming Service Provider in the JDK supports two environment properties to control timeout when connecting to, or reading from, the LDAP server. These two properties are of general interest for a user of the API and would deserve to be documented more prominently, as was done for similar JNDI/DNS properties when JDK-8228580 was fixed.

Solution

Document these properties in the module-info of the java.naming module, since there is no jdk.naming.ldap module implementation.

Specification

 /**
  * Defines the Java Naming and Directory Interface (JNDI) API.
+ * <p>
+ * Common standard JNDI environment properties that may be supported
+ * by JNDI providers are defined and documented in
+ * {@link javax.naming.Context}. Specific JNDI provider implementations
+ * may also support other environment properties, which are specific
+ * to their implementation.
+ *
+ * @implNote
+ * The following implementation specific properties are supported by the
+ * default LDAP Naming Service Provider implementation in the JDK:
+ * <ul>
+ *     <li>{@code com.sun.jndi.ldap.connect.timeout}:
+ *         <br>The value of this property is the string representation
+ *         of an integer representing the connection timeout in
+ *         milliseconds. If the LDAP provider cannot establish a
+ *         connection within that period, it aborts the connection attempt.
+ *         The integer should be greater than zero. An integer less than
+ *         or equal to zero means to use the network protocol's (i.e., TCP's)
+ *         timeout value.
+ *         <br> If this property is not specified, the default is to wait
+ *         for the connection to be established or until the underlying
+ *         network times out.
+ *     </li>
+ *     <li>{@code com.sun.jndi.ldap.read.timeout}:
+ *         <br>The value of this property is the string representation
+ *         of an integer representing the read timeout in milliseconds
+ *         for LDAP operations. If the LDAP provider cannot get a LDAP
+ *         response within that period, it aborts the read attempt. The
+ *         integer should be greater than zero. An integer less than or
+ *         equal to zero means no read timeout is specified which is equivalent
+ *         to waiting for the response infinitely until it is received.
+ *         <br>If this property is not specified, the default is to wait
+ *         for the response until it is received.
+ *     </li>
+ * </ul>
 *