8248865: Document JNDI/LDAP timeout properties

Documentation added in the module-info of java.naming

Backport-of: d308558d4fb98fc85b6574a9de229b255fc7ee7c

Author: Alexey Bakhtin

src/java.naming/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2020, 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
@@ -25,6 +25,41 @@
 
 /**
  * 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>
  *
  * @provides javax.naming.ldap.spi.LdapDnsProvider
  *
@@ -56,4 +91,3 @@
     provides java.security.Provider with
         sun.security.provider.certpath.ldap.JdkLDAP;
 }
-