docs: document JVM DNS cache TTL interaction for hostname contact points

Explain that hostname contact points are re-resolved on every connection
attempt but are subject to the JVM DNS cache (default 30s TTL when no
security manager is installed). Document that the effective recovery time
after a node replacement is max(networkaddress.cache.ttl, reconnection
backoff), and that lowering the TTL below the reconnection base delay
yields no benefit. Correct the resolve-contact-points=false description
to clarify it still goes through the JVM DNS cache via Netty's
DefaultNameResolver.

Author: nikagra

core/src/main/resources/reference.conf

@@ -1161,15 +1161,28 @@ datastax-java-driver {
 
   # Whether to resolve the addresses passed to `basic.contact-points`.
   #
-  # If this is true, addresses are created with `InetSocketAddress(String, int)`: the host name will
-  # be resolved the first time, and the driver will use the resolved IP address for all subsequent
-  # connection attempts.
+  # If this is true (default):
+  # - IP literals are resolved once at startup; the driver reuses that IP for all subsequent
+  #   connection attempts.
+  # - Hostnames (non-IP values) are re-resolved on every connection attempt via
+  #   `InetAddress.getAllByName()`. This lets the driver automatically pick up a new IP address
+  #   after a node replacement updates the DNS entry, without requiring a driver restart. The JVM
+  #   has its own DNS cache (default TTL: 30 seconds when no security manager is installed), so
+  #   the driver may observe the updated IP up to ~30 seconds after the DNS entry changes. To
+  #   reduce that lag, lower the JVM security property `networkaddress.cache.ttl`, either in
+  #   `$JAVA_HOME/conf/security/java.security` or programmatically:
+  #     java.security.Security.setProperty("networkaddress.cache.ttl", "5");
+  #   Note that the effective recovery time after a node replacement is
+  #   max(networkaddress.cache.ttl, reconnection backoff), so tuning the TTL below the
+  #   reconnection base delay yields no benefit. Setting it to 0 disables the JVM DNS cache
+  #   entirely, causing a live DNS query on every connection attempt — this trades lower lag for
+  #   increased DNS load and sensitivity to transient DNS failures.
   #
   # If this is false, addresses are created with `InetSocketAddress.createUnresolved()`: the host
-  # name will be resolved again every time the driver opens a new connection. This is useful for
-  # containerized environments where DNS records are more likely to change over time (note that the
-  # JVM and OS have their own DNS caching mechanisms, so you might need additional configuration
-  # beyond the driver).
+  # name will be resolved every time the driver opens a new connection, with resolution delegated
+  # to Netty's address resolver (which uses `InetAddress.getAllByName()` internally and is
+  # therefore still subject to the JVM DNS cache). Unlike the true case, this also re-resolves
+  # IP literals on every connection, and does not perform round-robin across multiple A-records.
   #
   # This option only applies to the contact points specified in the configuration. It has no effect
   # on:

manual/core/README.md

@@ -125,6 +125,28 @@ datastax-java-driver {
 For more details about the local datacenter, refer to the [load balancing
 policy](load_balancing/#local-only) section.
 
+When a contact point is specified as a hostname (rather than an IP literal), the driver re-resolves
+it via DNS on every connection attempt. This allows the driver to automatically pick up a new IP
+address after a node replacement updates the DNS entry, without requiring a restart. However, the
+JVM maintains its own DNS cache: by default (when no security manager is installed) successful
+lookups are cached for 30 seconds, so there may be a lag before the updated IP is used.
+
+To reduce the lag, lower the JVM security property `networkaddress.cache.ttl` in
+`$JAVA_HOME/conf/security/java.security` or programmatically before building the session:
+
+```java
+java.security.Security.setProperty("networkaddress.cache.ttl", "5");
+```
+
+The effective recovery time after a node replacement is
+`max(networkaddress.cache.ttl, reconnection backoff)`, so there is no benefit to setting the TTL
+lower than your reconnection base delay. Setting it to `0` disables the JVM DNS cache entirely,
+causing a live DNS query on every connection attempt — this minimises lag but increases DNS load
+and makes reconnection sensitive to transient DNS failures.
+
+See also the `advanced.resolve-contact-points` option in the
+[configuration reference](configuration/reference/) for further details.
+
 ##### Keyspace
 
 By default, a session isn't tied to any specific keyspace. You'll need to prefix table names in your