Add a maximum idle duration health check

Added a new LDAP connection pool health check that can be used to
replace connections that have remained idle for longer than a
specified length of time.  This is primarily useful in cases where
the associated directory servers (or intermediate networking
equipment) may terminate connections that have remained idle for too
long.  Note that in connection pools that may contain connections
across multiple servers, you should probably set a maximum
connection age for the pool rather than using this health check, as
this will better allow the pool to return to a balanced state more
quickly after a failure has caused connections to migrate away from
one or more servers.  Also note that health checks that attempt to
actually communicate with the associated server over LDAP may be
preferred over this health check because not only will they do a
better job of ensuring that connections are actually usable, but
the communication that they perform will also prevent the
connections from being seen as idle.

docs/release-notes.html

@@ -6,6 +6,35 @@
 
               <h2>Release Notes</h2>
 
+              <h3>Version 7.0.1</h3>
+
+              <p>
+                The following changes were made between the 7.0.0 and 7.0.1 releases:
+              </p>
+
+              <ul>
+                <li>
+                  Added a new LDAP connection pool health check that can be used to replace
+                  connections that have remained idle for longer than a specified length of time.
+                  This is primarily useful in cases where the associated directory servers (or
+                  intermediate networking equipment) may terminate connections that have remained
+                  idle for too long.  Note that in connection pools that may contain connections
+                  across multiple servers, you should probably set a maximum connection age for the
+                  pool rather than using this health check, as this will better allow the pool to
+                  return to a balanced state more quickly after a failure has caused connections to
+                  migrate away from one or more servers.  Also note that health checks that attempt
+                  to actually communicate with the associated server over LDAP may be preferred
+                  over this health check because not only will they do a better job of ensuring
+                  that connections are actually usable, but the communication that they perform
+                  will also prevent the connections from being seen as idle.
+                  <br><br>
+                </li>
+              </ul>
+
+              <p></p>
+
+
+
               <h3>Version 7.0.0</h3>
 
               <p>

messages/unboundid-ldapsdk-ldap.properties

@@ -934,4 +934,7 @@ ERR_REFERRAL_POOL_UNSUPPORTED_BIND_TYPE=Unable to use the pooled referral \
 ERR_REFERRAL_POOL_CANNOT_CREATE_SSL_SOCKET_FACTORY=An error occurred while \
   attempting to create an SSL socket factory to use when performing TLS \
   negotiation:  {0}
+ERR_IDLE_HEALTH_CHECK_CONNECTION_IDLE=The LDAP connection has been idle for \
+  {0,number,0}ms, which is longer than the maximum allowed idle duration of \
+  {1,number,0}ms.
 

src/com/unboundid/ldap/sdk/LDAPConnectionPoolHealthCheck.java

@@ -273,7 +273,7 @@ public void ensureConnectionValidForContinuedUse(
 
   /**
    * Performs any processing that may be appropriate on an ongoing basis for the
-   * connection pool that is not related to the pool itself rather than any
+   * connection pool that is related to the pool itself rather than any
    * individual connection.  This method will be invoked by the pool's
    * {@link LDAPConnectionPoolHealthCheckThread} at an interval specified by the
    * pool's {@link AbstractConnectionPool#getHealthCheckIntervalMillis()}

src/com/unboundid/ldap/sdk/MaximumIdleDurationLDAPConnectionPoolHealthCheck.java

@@ -0,0 +1,212 @@
+/*
+ * Copyright 2024 Ping Identity Corporation
+ * All Rights Reserved.
+ */
+/*
+ * Copyright 2024 Ping Identity Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/*
+ * Copyright (C) 2024 Ping Identity Corporation
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License (GPLv2 only)
+ * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <http://www.gnu.org/licenses>.
+ */
+package com.unboundid.ldap.sdk;
+
+
+
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.LongAdder;
+
+import com.unboundid.util.NotMutable;
+import com.unboundid.util.NotNull;
+import com.unboundid.util.ThreadSafety;
+import com.unboundid.util.ThreadSafetyLevel;
+import com.unboundid.util.Validator;
+
+import static com.unboundid.ldap.sdk.LDAPMessages.*;
+
+
+
+/**
+ * This class provides an implementation of an LDAP connection pool health check
+ * that will cause the associated connection pool to consider a connection
+ * invalid after it has remained idle (as determined using the
+ * {@link LDAPConnection#getLastCommunicationTime()} method) for more than a
+ * specified length of time.  This is primarily useful in cases where the
+ * associated directory servers (or some intermediate networking equipment) may
+ * terminate connections that have remained idle for too long.
+ * <BR><BR>
+ * Note that in connection pools that may contain connections across multiple
+ * servers, you should probably use the
+ * {@link LDAPConnectionPool#setMaxConnectionAgeMillis(long)} method instead of
+ * this health check to ensure that connections are automatically refreshed
+ * after a specified duration, regardless of whether they have been idle.
+ * Setting a maximum connection age will help ensure that connections in the
+ * pool will return to a relatively balanced state after a failure has caused
+ * connections to migrate away from one or more of those servers.
+ * <BR><BR>
+ * Also note that as an alternative to this health check, you may wish to
+ * consider a health check that actually attempts to communicate with the
+ * destination server over LDAP (e.g., the
+ * {@link GetEntryLDAPConnectionPoolHealthCheck}).  Not only will those types of
+ * health checks do a better job of ensuring that the connection is still valid
+ * (and that the server to which it is established is responsive), but the
+ * communication that they perform will also prevent them from being considered
+ * idle.
+ *
+ * @see  LDAPConnectionPool
+ * @see  LDAPConnectionPoolHealthCheck
+ */
+@NotMutable()
+@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
+public final class MaximumIdleDurationLDAPConnectionPoolHealthCheck
+       extends LDAPConnectionPoolHealthCheck
+{
+  // A counter that will be incremented any time an idle connection is
+  // identified.
+  @NotNull private final LongAdder idleConnectionCounter;
+
+  // The maximum length of time in milliseconds that connections will be allowed
+  // to remain idle before they will be replaced by the associated connection
+  // pool.
+  private final long maximumIdleDurationMillis;
+
+
+
+  /**
+   * Creates a new instance of this health check that will use the specified
+   * maximum idle duration.
+   *
+   * @param  maximumIdleDurationValue
+   *              The value that specifies the maximum length of time, in
+   *              conjunction with the specified time unit, that connections
+   *              will be allowed to remain idle before they will be replaced
+   *              by the associated connection pool.  This value must be greater
+   *              than zero.
+   * @param  maximumIdleDurationTimeUnit
+   *              The time unit to use when interpreting the provided maximum
+   *              idle duration value.  It must not be {@code null}.
+   */
+  public MaximumIdleDurationLDAPConnectionPoolHealthCheck(
+       final long maximumIdleDurationValue,
+       @NotNull final TimeUnit maximumIdleDurationTimeUnit)
+  {
+    this(maximumIdleDurationTimeUnit.toMillis(maximumIdleDurationValue));
+  }
+
+
+
+  /**
+   * Creates a new instance of this health check that will use the specified
+   * maximum idle duration.
+   *
+   * @param  maximumIdleDurationMillis
+   *              The maximum length of time in milliseconds that connections
+   *              will be allowed to remain idle before they will be replaced by
+   *              the associated connection pool.  This value must be greater
+   *              than zero.
+   */
+  public MaximumIdleDurationLDAPConnectionPoolHealthCheck(
+              final long maximumIdleDurationMillis)
+  {
+    Validator.ensureTrue((maximumIdleDurationMillis > 0L),
+         "MaximumIdleDurationLDAPConnectionPoolHealthCheck." +
+              "maximumIdleDurationMillis must be greater than zero.");
+
+    this.maximumIdleDurationMillis = maximumIdleDurationMillis;
+
+    idleConnectionCounter = new LongAdder();
+  }
+
+
+
+  /**
+   * Retrieves the maximum length of time in milliseconds that connections will
+   * be allowed to remain idle before they will be replaced by the associated
+   * connection pool.
+   *
+   * @return  The maximum length of time in milliseconds that connections will
+   *          be allowed to remain idle before they will be replaced by the
+   *          associated connection pool.
+   */
+  public long getMaximumIdleDurationMillis()
+  {
+    return maximumIdleDurationMillis;
+  }
+
+
+
+  /**
+   * Retrieves the number of pooled connections that this health check has
+   * considered invalid because of their idle duration.
+   *
+   * @return  The number of pooled connections that this health check has
+   *          considered invalid because of their idle duration.
+   */
+  public long getIdleConnectionCount()
+  {
+    return idleConnectionCounter.longValue();
+  }
+
+
+
+  /**
+   * {@inheritDoc}
+   */
+  @Override()
+  public void ensureConnectionValidForContinuedUse(
+                   @NotNull final LDAPConnection connection)
+         throws LDAPException
+  {
+    final long currentTime = System.currentTimeMillis();
+    final long lastCommunicationTime = connection.getLastCommunicationTime();
+    final long idleDurationMillis = currentTime - lastCommunicationTime;
+
+    if (idleDurationMillis > maximumIdleDurationMillis)
+    {
+      idleConnectionCounter.increment();
+      throw new LDAPException(ResultCode.TIMEOUT,
+           ERR_IDLE_HEALTH_CHECK_CONNECTION_IDLE.get(idleDurationMillis,
+                maximumIdleDurationMillis));
+    }
+  }
+
+
+
+  /**
+   * Appends a string representation of this LDAP connection pool health check
+   * to the provided buffer.
+   *
+   * @param  buffer  The buffer to which the information should be appended.
+   */
+  public void toString(@NotNull final StringBuilder buffer)
+  {
+    buffer.append("MaximumIdleDurationLDAPConnectionPoolHealthCheck(" +
+         "maximumIdleDurationMillis=");
+    buffer.append(maximumIdleDurationMillis);
+    buffer.append(')');
+  }
+}

tests/unit/src/com/unboundid/ldap/sdk/MaximumIdleDurationLDAPConnectionPoolHealthCheckTestCase.java

@@ -0,0 +1,125 @@
+/*
+ * Copyright 2024 Ping Identity Corporation
+ * All Rights Reserved.
+ */
+/*
+ * Copyright 2024 Ping Identity Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/*
+ * Copyright (C) 2024 Ping Identity Corporation
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License (GPLv2 only)
+ * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <http://www.gnu.org/licenses>.
+ */
+package com.unboundid.ldap.sdk;
+
+
+
+import java.util.concurrent.TimeUnit;
+
+import org.testng.annotations.Test;
+
+import com.unboundid.ldap.listener.InMemoryDirectoryServer;
+
+
+
+/**
+ * This class provides a set of test cases that verify the behavior of the
+ * maximum idle duration LDAP connection pool health check.
+ */
+public final class MaximumIdleDurationLDAPConnectionPoolHealthCheckTestCase
+       extends LDAPSDKTestCase
+{
+  /**
+   * Tests the health check for connections that should not be considered idle.
+   *
+   * @throws  Exception  If an unexpected problem occurs.
+   */
+  @Test()
+  public void testConnectionsNotIdle()
+         throws Exception
+  {
+    final InMemoryDirectoryServer ds = getTestDS();
+
+    final SingleServerSet serverSet =
+         new SingleServerSet("127.0.0.1", ds.getListenPort());
+    try (LDAPConnectionPool pool = new LDAPConnectionPool(serverSet, null, 1))
+    {
+      final MaximumIdleDurationLDAPConnectionPoolHealthCheck healthCheck =
+           new MaximumIdleDurationLDAPConnectionPoolHealthCheck(1,
+                TimeUnit.HOURS);
+      assertEquals(healthCheck.getMaximumIdleDurationMillis(), 3_600_000L);
+      assertEquals(healthCheck.getIdleConnectionCount(), 0L);
+      assertNotNull(healthCheck.toString());
+
+      pool.setHealthCheck(healthCheck);
+      pool.setHealthCheckIntervalMillis(100L);
+
+      Thread.sleep(1000L);
+
+      assertEquals(healthCheck.getIdleConnectionCount(), 0L);
+
+      assertNotNull(pool.getRootDSE());
+
+      Thread.sleep(1000L);
+
+      assertEquals(healthCheck.getMaximumIdleDurationMillis(), 3_600_000L);
+      assertEquals(healthCheck.getIdleConnectionCount(), 0L);
+      assertNotNull(healthCheck.toString());
+    }
+  }
+
+
+
+  /**
+   * Tests the health check for connections that should be considered idle.
+   *
+   * @throws  Exception  If an unexpected problem occurs.
+   */
+  @Test()
+  public void testConnectionsIdle()
+         throws Exception
+  {
+    final InMemoryDirectoryServer ds = getTestDS();
+
+    final SingleServerSet serverSet =
+         new SingleServerSet("127.0.0.1", ds.getListenPort());
+    try (LDAPConnectionPool pool = new LDAPConnectionPool(serverSet, null, 1))
+    {
+      final MaximumIdleDurationLDAPConnectionPoolHealthCheck healthCheck =
+           new MaximumIdleDurationLDAPConnectionPoolHealthCheck(100L);
+      assertEquals(healthCheck.getMaximumIdleDurationMillis(), 100L);
+      assertEquals(healthCheck.getIdleConnectionCount(), 0L);
+      assertNotNull(healthCheck.toString());
+
+      pool.setHealthCheck(healthCheck);
+      pool.setHealthCheckIntervalMillis(100L);
+
+      Thread.sleep(1000L);
+
+      assertTrue(healthCheck.getIdleConnectionCount() > 0L);
+    }
+  }
+}