001/*
002 * Copyright 2023 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2023 Ping Identity Corporation
007 *
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *    http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020/*
021 * Copyright (C) 2023 Ping Identity Corporation
022 *
023 * This program is free software; you can redistribute it and/or modify
024 * it under the terms of the GNU General Public License (GPLv2 only)
025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
026 * as published by the Free Software Foundation.
027 *
028 * This program is distributed in the hope that it will be useful,
029 * but WITHOUT ANY WARRANTY; without even the implied warranty of
030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
031 * GNU General Public License for more details.
032 *
033 * You should have received a copy of the GNU General Public License
034 * along with this program; if not, see <http://www.gnu.org/licenses>.
035 */
036package com.unboundid.ldap.sdk;
037
038
039
040import java.util.concurrent.TimeUnit;
041import javax.net.ssl.SSLSocketFactory;
042
043import com.unboundid.util.Mutable;
044import com.unboundid.util.NotNull;
045import com.unboundid.util.Nullable;
046import com.unboundid.util.ThreadSafety;
047import com.unboundid.util.ThreadSafetyLevel;
048import com.unboundid.util.Validator;
049
050
051
052/**
053 * This class defines a set of properties for use when creating a
054 * {@link PooledReferralConnector}.  Changing any properties after a
055 * connector is created will not cause any changes in the connector.
056 */
057@Mutable()
058@ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE)
059public final class PooledReferralConnectorProperties
060{
061  // The bind request to use to authenticate to pooled connections, as an
062  // alternative to the bind request used to authenticate connections on which
063  // referrals were received.
064  @Nullable private BindRequest bindRequest;
065
066  // Indicates whether to retry operations on a newly established connection
067  // if the initial attempt fails in a way that suggests that the pooled
068  // connection may not be valid.
069  private boolean retryFailedOperationsDueToInvalidConnections;
070
071  // The initial number of connections to establish when creating a connection
072  // pool.
073  private int initialConnectionsPerPool;
074
075  // The maximum number of connections to maintain in each of the connection
076  // pools.
077  private int maximumConnectionsPerPool;
078
079  // The connection options to use when establishing new connections, as an
080  // alternative to the connection options used for a connection on which a
081  // referral was received.
082  @Nullable private LDAPConnectionOptions connectionOptions;
083
084  // A health check to use for the connection pools.
085  @Nullable private LDAPConnectionPoolHealthCheck healthCheck;
086
087  // The interval that the background thread should use when checking for
088  // cleanup operations.
089  private long backgroundThreadCheckIntervalMillis;
090
091  // The health check interval in milliseconds to use for the connection pools.
092  private long healthCheckIntervalMillis;
093
094  // The maximum length of time in milliseconds that any individual pooled
095  // connection should be allowed to remain established.
096  private long maximumConnectionAgeMillis;
097
098  // The maximum length of time in milliseconds that any connection pool should
099  // be allowed to remain active.
100  private long maximumPoolAgeMillis;
101
102  // The maximum length of time in milliseconds that should be allowed to pass
103  // since a connection pool was last used to follow a referral before it is
104  // discarded.
105  private long maximumPoolIdleDurationMillis;
106
107  // The security type to use when establishing connections in response to
108  // referral URLs with a scheme of "ldap".
109  @NotNull private PooledReferralConnectorLDAPURLSecurityType
110       ldapURLSecurityType;
111
112  // The SSL socket factory to use when performing TLS negotiation, as an
113  // alternative to the socket factory from the associated connection.
114  @Nullable private SSLSocketFactory sslSocketFactory;
115
116
117
118  /**
119   * Creates a new set of pooled referral connector properties with the default
120   * settings.
121   */
122  public PooledReferralConnectorProperties()
123  {
124    bindRequest = null;
125    retryFailedOperationsDueToInvalidConnections = true;
126    initialConnectionsPerPool = 1;
127    maximumConnectionsPerPool = 10;
128    connectionOptions = null;
129    healthCheck = null;
130    backgroundThreadCheckIntervalMillis = TimeUnit.SECONDS.toMillis(10L);
131    healthCheckIntervalMillis = TimeUnit.MINUTES.toMillis(1L);
132    maximumConnectionAgeMillis = TimeUnit.MINUTES.toMillis(30L);
133    maximumPoolAgeMillis = 0L;
134    maximumPoolIdleDurationMillis = TimeUnit.HOURS.toMillis(1L);
135    ldapURLSecurityType = PooledReferralConnectorLDAPURLSecurityType.
136         CONDITIONALLY_USE_LDAP_AND_CONDITIONALLY_USE_START_TLS;
137    sslSocketFactory = null;
138  }
139
140
141
142  /**
143   * Creates a new set of pooled referral connector properties that is a
144   * duplicate of the provided set of properties.
145   *
146   * @param  properties  The set of properties to duplicate.  It must not be
147   *                     {@code null}.
148   */
149  public PooledReferralConnectorProperties(
150              @NotNull final PooledReferralConnectorProperties properties)
151  {
152    bindRequest = properties.bindRequest;
153    retryFailedOperationsDueToInvalidConnections =
154         properties.retryFailedOperationsDueToInvalidConnections;
155    initialConnectionsPerPool = properties.initialConnectionsPerPool;
156    maximumConnectionsPerPool = properties.maximumConnectionsPerPool;
157    connectionOptions = properties.connectionOptions;
158    healthCheck = properties.healthCheck;
159    backgroundThreadCheckIntervalMillis =
160         properties.backgroundThreadCheckIntervalMillis;
161    healthCheckIntervalMillis = properties.healthCheckIntervalMillis;
162    maximumConnectionAgeMillis = properties.maximumConnectionAgeMillis;
163    maximumPoolAgeMillis = properties.maximumPoolAgeMillis;
164    maximumPoolIdleDurationMillis = properties.maximumPoolIdleDurationMillis;
165    ldapURLSecurityType = properties.ldapURLSecurityType;
166    sslSocketFactory = properties.sslSocketFactory;
167  }
168
169
170
171  /**
172   * Retrieves the initial number of connections to establish when creating a
173   * new connection pool for the purpose of following referrals.  By default,
174   * only a single connection will be established.
175   *
176   * @return  The initial number of connections to establish when creating a
177   *          new connection pool for the purpose of following referrals.
178   */
179  public int getInitialConnectionsPerPool()
180  {
181    return initialConnectionsPerPool;
182  }
183
184
185
186  /**
187   * Specifies the initial number of connections to establish when creating a
188   * new connection pool for the purpose of following referrals.  By default,
189   * only a single connection will be established.
190   *
191   * @param  initialConnectionsPerPool
192   *              The initial number of connections to establish when creating a
193   *              new connection pool for the purpose of following referrals.
194   *              It must be greater than or equal to 1, and the initial number
195   *              of connections per pool must ultimately be less than or equal
196   *              to the maximum number of connections per pool.
197   */
198  public void setInitialConnectionsPerPool(final int initialConnectionsPerPool)
199  {
200    Validator.ensureTrue((initialConnectionsPerPool >= 1),
201         "PooledReferralConnectorProperties.initialConnectionsPerPool must " +
202              "be greater than or equal to one.");
203
204    this.initialConnectionsPerPool = initialConnectionsPerPool;
205  }
206
207
208
209  /**
210   * Retrieves the maximum number of idle connections that the server should
211   * maintain in each connection pool used for following referrals.  By default,
212   * a maximum of ten connections will be retained.
213   *
214   * @return  The maximum number of idle connections that the server should
215   *          maintain in each connection pool used for following referrals.
216   */
217  public int getMaximumConnectionsPerPool()
218  {
219    return maximumConnectionsPerPool;
220  }
221
222
223
224  /**
225   * Specifies the maximum number of idle connections that the server should
226   * maintain in each connection pool used for following referrals.  By default,
227   * a maximum of ten connections will be retained.
228   *
229   * @param  maximumConnectionsPerPool
230   *              The maximum number of idle connections that the server should
231   *              maintain in each connection pool used for following referrals.
232   *              It must be greater than or equal to 1, and the initial number
233   *              of connections per pool must ultimately be less than or equal
234   *              to the maximum number of connections per pool.
235   */
236  public void setMaximumConnectionsPerPool(final int maximumConnectionsPerPool)
237  {
238    Validator.ensureTrue((initialConnectionsPerPool >= 1),
239         "PooledReferralConnectorProperties.maximumConnectionsPerPool must " +
240              "be greater than or equal to one.");
241
242    this.maximumConnectionsPerPool = maximumConnectionsPerPool;
243  }
244
245
246
247  /**
248   * Indicates whether the connection pools should be configured to
249   * automatically retry an operation on a newly established connection if the
250   * initial attempt fails in a manner that suggests that the connection may no
251   * longer be valid.  By default, operations that fail in that manner will
252   * automatically be retried.
253   *
254   * @return  {@code true} if connection pools should be configured to
255   *          automatically retry an operation on a newly established connection
256   *          if the initial attempt fails in a manner that suggests the
257   *          connection may no longer be valid, or {@code false} if not.
258   */
259  public boolean retryFailedOperationsDueToInvalidConnections()
260  {
261    return retryFailedOperationsDueToInvalidConnections;
262  }
263
264
265
266  /**
267   * Specifies whether the connection pools should be configured to
268   * automatically retry an operation on a newly established connection if the
269   * initial attempt fails in a manner that suggests that the connection may no
270   * longer be valid.  By default, operations that fail in that manner will
271   * automatically be retried.
272   *
273   * @param  retryFailedOperationsDueToInvalidConnections
274   *              Indicates whether the connection pools should be configured to
275   *              automatically retry an operation on a newly established
276   *              connection if the initial attempt fails in a manner that
277   *              suggests that the connection may no longer be valid.
278   */
279  public void setRetryFailedOperationsDueToInvalidConnections(
280                   final boolean retryFailedOperationsDueToInvalidConnections)
281  {
282    this.retryFailedOperationsDueToInvalidConnections =
283         retryFailedOperationsDueToInvalidConnections;
284  }
285
286
287
288  /**
289   * Retrieves the maximum length of time in milliseconds that each pooled
290   * connection may remain established.  If a pooled connection is established
291   * for longer than this duration, it will be closed and re-established.  By
292   * default, pooled connections will be allowed to remain established for up
293   * to 30 minutes.  A value of zero indicates that pooled connections will be
294   * allowed to remain established indefinitely (or at least until it is
295   * determined to be invalid or the pool is closed).
296   *
297   * @return  The maximum length of time in milliseconds that each pooled
298   *          connection may remain established.
299   */
300  public long getMaximumConnectionAgeMillis()
301  {
302    return maximumConnectionAgeMillis;
303  }
304
305
306
307  /**
308   * Specifies the maximum length of time in milliseconds that each pooled
309   * connection may remain established.  If a pooled connection is established
310   * for longer than this duration, it will be closed and re-established.  By
311   * default, pooled connections will be allowed to remain established for up
312   * to 30 minutes.  A value that is less than or equal to zero indicates that
313   * pooled connections will be allowed to remain established indefinitely (or
314   * at least until it is determined to be invalid or the pool is closed).
315   *
316   * @param  maximumConnectionAgeMillis
317   *              The maximum length of time in milliseconds that each pooled
318   *              connection may remain established.  A value that is less than
319   *              or equal to zero indicates that pooled connections will be
320   *              allowed to remain established indefinitely.
321   */
322  public void setMaximumConnectionAgeMillis(
323                   final long maximumConnectionAgeMillis)
324  {
325    if (maximumConnectionAgeMillis > 0L)
326    {
327      this.maximumConnectionAgeMillis = maximumConnectionAgeMillis;
328    }
329    else
330    {
331      this.maximumConnectionAgeMillis = 0L;
332    }
333  }
334
335
336
337  /**
338   * Retrieves the maximum length of time in milliseconds that a connection pool
339   * created for the purpose of following referrals should be retained,
340   * regardless of how often it is used.  If it has been longer than this length
341   * of time since a referral connection pool was created, it will be
342   * automatically closed, and a new pool will be created if another applicable
343   * referral is received.  A value of zero, which is the default, indicates
344   * that connection pools should not be automatically closed based on the
345   * length of time since they were created.
346   *
347   * @return  The maximum length of time in milliseconds that a referral
348   *          connection pool should be retained, or zero if connection pools
349   *          should not be automatically closed based on the length of time
350   *          since they were created.
351   */
352  public long getMaximumPoolAgeMillis()
353  {
354    return maximumPoolAgeMillis;
355  }
356
357
358
359  /**
360   * Specifies the maximum length of time in milliseconds that a connection pool
361   * created for the purpose of following referrals should be retained,
362   * regardless of how often it is used.  If it has been longer than this length
363   * of time since a referral connection pool was created, it will be
364   * automatically closed, and a new pool will be created if another applicable
365   * referral is received.  A value that is less than or equal to zero (with the
366   * default value being zero) indicates that connection pools should not be
367   * automatically closed based on the length of time since they were created.
368   *
369   * @param  maximumPoolAgeMillis
370   *              The maximum length of time in milliseconds that a referral
371   *              connection pool should be retained.  A value that is less than
372   *              or equal to zero indicates that connection pools should not be
373   *              automatically closed based on their age.
374   */
375  public void setMaximumPoolAgeMillis(final long maximumPoolAgeMillis)
376  {
377    if (maximumPoolAgeMillis > 0L)
378    {
379      this.maximumPoolAgeMillis = maximumPoolAgeMillis;
380    }
381    else
382    {
383      this.maximumPoolAgeMillis = 0L;
384    }
385  }
386
387
388
389  /**
390   * Retrieves the maximum length of time in milliseconds that a connection pool
391   * created for the purpose of following referrals should be retained after its
392   * most recent use.  By default, referral connection pools will be
393   * automatically discarded if they have remained unused for over one hour.  A
394   * value of zero indicates that pools may remain in use indefinitely,
395   * regardless of how long it has been since they were last used.
396   *
397   * @return  The maximum length of time in milliseconds that a connection pool
398   *          created for the purpose of following referrals should be retained
399   *          after its most recent use, or zero if referral connection pools
400   *          should not be discarded regardless of how long it has been since
401   *          they were last used.
402   */
403  public long getMaximumPoolIdleDurationMillis()
404  {
405    return maximumPoolIdleDurationMillis;
406  }
407
408
409
410  /**
411   * Specifies the maximum length of time in milliseconds that a connection pool
412   * created for the purpose of following referrals should be retained after its
413   * most recent use.  By default, referral connection pools will be
414   * automatically discarded if they have remained unused for over one hour.  A
415   * value of zero indicates that pools may remain in use indefinitely,
416   * regardless of how long it has been since they were last used.
417   *
418   * @param  maximumPoolIdleDurationMillis
419   *              The maximum length of time in milliseconds that a connection
420   *              pool created for the purpose of following referrals should be
421   *              retained after its most recent use.  A value that is less than
422   *              or equal to zero indicates that connection pools should not be
423   *              automatically closed based on how long it has been since they
424   *              were last used.
425   */
426  public void setMaximumPoolIdleDurationMillis(
427                   final long maximumPoolIdleDurationMillis)
428  {
429    if (maximumPoolIdleDurationMillis > 0L)
430    {
431      this.maximumPoolIdleDurationMillis = maximumPoolIdleDurationMillis;
432    }
433    else
434    {
435      this.maximumPoolIdleDurationMillis = 0L;
436    }
437  }
438
439
440
441  /**
442   * Retrieves the health check that should be used to determine whether pooled
443   * connections are still valid.  By default, no special health checking will
444   * be performed for pooled connections (aside from checking them against
445   * the maximum connection age).
446   *
447   * @return  The health check that should be used to determine whether pooled
448   *          connections are still valid, or {@code null} if no special
449   *          health checking should be performed.
450   */
451  @Nullable()
452  public LDAPConnectionPoolHealthCheck getHealthCheck()
453  {
454    return healthCheck;
455  }
456
457
458
459  /**
460   * Specifies the health check that should be used to determine whether pooled
461   * connections are still valid.  By default, no special health checking will
462   * be performed for pooled connections (aside from checking them against
463   * the maximum connection age).
464   *
465   * @param  healthCheck
466   *              The health check that should be used to determine whether
467   *              pooled connections are still valid.  It may be {@code null} if
468   *              no special health checking should be performed.
469   */
470  public void setHealthCheck(
471                   @Nullable final LDAPConnectionPoolHealthCheck healthCheck)
472  {
473    this.healthCheck = healthCheck;
474  }
475
476
477
478  /**
479   * Retrieves the length of time in milliseconds between background health
480   * checks performed against pooled connections.  By default, background health
481   * checks will be performed every sixty seconds.
482   *
483   * @return  The length of time in milliseconds between background health
484   *          checks performed against pooled connections.
485   */
486  public long getHealthCheckIntervalMillis()
487  {
488    return healthCheckIntervalMillis;
489  }
490
491
492
493  /**
494   * Specifies the length of time in milliseconds between background health
495   * checks performed against pooled connections.
496   *
497   * @param  healthCheckIntervalMillis
498   *              The length of time in milliseconds between background health
499   *              checks performed against pooled connections.  It must be
500   *              greater than zero.
501   */
502  public void setHealthCheckIntervalMillis(
503                   final long healthCheckIntervalMillis)
504  {
505    Validator.ensureTrue((healthCheckIntervalMillis > 0L),
506         "PooledReferralConnectorProperties.healthCheckIntervalMillis must " +
507              "be greater than zero.");
508
509    this.healthCheckIntervalMillis = healthCheckIntervalMillis;
510  }
511
512
513
514  /**
515   * Retrieves the bind request that should be used to authenticate pooled
516   * connections, if defined.  By default, pooled connections will be
517   * authenticated with the same bind request that was used to authenticate
518   * the connection on which the referral was received (with separate pools used
519   * for referrals received on connections authenticated as different users).
520   *
521   * @return  The bind request that should be used to authenticate pooled
522   *          connections, or {@code null} if pooled connections should be
523   *          authenticated with the same bind request that was used to
524   *          authenticate the connection on which the referral was received.
525   */
526  @Nullable()
527  public BindRequest getBindRequest()
528  {
529    return bindRequest;
530  }
531
532
533
534  /**
535   * Specifies the bind request that should be used to authenticate pooled
536   * connections.  By default, pooled connections will be authenticated with the
537   * same bind request that was used to  authenticate the connection on which
538   * the referral was received (with separate pools used for referrals received
539   * on connections authenticated as different users)., but this method may be
540   * used to override that and explicitly specify a bind request to use for
541   * authenticating all pooled connections.
542   *
543   * @param  bindRequest
544   *              The bind request that should be used to authenticate pooled
545   *              connections.  It may be {@code null} if connections should be
546   *              authenticated with the same bind request used to authenticate
547   *              a connection on which a referral was received (with separate
548   *              pools used for referrals received on connections authenticated
549   *              as different users).
550   */
551  public void setBindRequest(@Nullable final BindRequest bindRequest)
552  {
553    this.bindRequest = bindRequest;
554  }
555
556
557
558  /**
559   * Retrieves the set of options that will be used when establishing new pooled
560   * connections for the purpose of following referrals.  By default, new
561   * connections will use the same set of options as the connection on which a
562   * referral was received.
563   *
564   * @return  The set of options that will be used when establishing new
565   *          pooled connections for the purpose of following referrals, or
566   *          {@code null} if new connections will use the same set of options
567   *          as the connection on which a referral was received.
568   */
569  @Nullable()
570  public LDAPConnectionOptions getConnectionOptions()
571  {
572    if (connectionOptions == null)
573    {
574      return null;
575    }
576    else
577    {
578      return connectionOptions.duplicate();
579    }
580  }
581
582
583
584  /**
585   * Specifies the set of options that will be used when establishing new pooled
586   * connections for the purpose of following referrals.  By default, new
587   * connections will use the same set of options as the connection on which a
588   * referral was received.
589   *
590   * @param  connectionOptions
591   *              The set of options that will be used when establishing new
592   *              pooled connections for the purpose of following referrals.  It
593   *              may be {@code null} if new connections should use the same set
594   *              of options as the connection on which a referral was received.
595   */
596  public void setConnectionOptions(
597                   @Nullable final LDAPConnectionOptions connectionOptions)
598  {
599    this.connectionOptions = connectionOptions;
600  }
601
602
603
604  /**
605   * Indicates the type of communication security that the referral connector
606   * should use when creating connections for referral URLs with a scheme of
607   * "ldap".  Although the connector will always use LDAPS for connections
608   * created from referral URLs with a scheme of "ldaps", the determination of
609   * which security type to use for referral URLs with a scheme of "ldap" is
610   * more complicated because the official LDAP URL specification lists "ldap"
611   * as the only allowed scheme type.  See the class-level and value-level
612   * documentation in the {@link PooledReferralConnectorLDAPURLSecurityType}
613   * enum for more information.  By default, the
614   * {@code CONDITIONALLY_USE_LDAP_AND_CONDITIONALLY_USE_START_TLS} security
615   * type will be used.
616   *
617   * @return  The type of communication security that the referral connector
618   *          should use when creating connections for referral URLs with a
619   *          scheme of "ldap".
620   */
621  @NotNull()
622  public PooledReferralConnectorLDAPURLSecurityType getLDAPURLSecurityType()
623  {
624    return ldapURLSecurityType;
625  }
626
627
628
629  /**
630   * Specifies the type of communication security that the referral connector
631   * should use when creating connections for referral URLs with a scheme of
632   * "ldap".  Although the connector will always use LDAPS for connections
633   * created from referral URLs with a scheme of "ldaps", the determination of
634   * which security type to use for referral URLs with a scheme of "ldap" is
635   * more complicated because the official LDAP URL specification lists "ldap"
636   * as the only allowed scheme type.  See the class-level and value-level
637   * documentation in the {@link PooledReferralConnectorLDAPURLSecurityType}
638   * enum for more information.  By default, the
639   * {@code CONDITIONALLY_USE_LDAP_AND_CONDITIONALLY_USE_START_TLS} security
640   * type will be used.
641   *
642   * @param  ldapURLSecurityType
643   *              The type of communication security that the referral connector
644   *              should use when creating connections for referral URLs with a
645   *              scheme of "ldap".  It must not be {@code null}.
646   */
647  public void setLDAPURLSecurityType(
648                   @NotNull final PooledReferralConnectorLDAPURLSecurityType
649                        ldapURLSecurityType)
650  {
651    Validator.ensureNotNullWithMessage(ldapURLSecurityType,
652         "PooledReferralConnectorProperties.ldapURLSecurityType must not be " +
653              "null.");
654
655    this.ldapURLSecurityType = ldapURLSecurityType;
656  }
657
658
659
660  /**
661   * Retrieves the SSL socket factory that will be used when performing TLS
662   * negotiation on any new connections created for the purpose of following
663   * referrals.  By default, new pooled connections will use the same socket
664   * factory as the connection on which a referral was received.
665   *
666   * @return  The SSL socket factory that will be used when performing TLS
667   *          negotiation on any new connections created for the purpose of
668   *          following referrals, or {@code null} if new pooled connections
669   *          will use the same socket factory as the connection on which a
670   *          referral was received.
671   */
672  @Nullable()
673  public SSLSocketFactory getSSLSocketFactory()
674  {
675    return sslSocketFactory;
676  }
677
678
679
680  /**
681   * Specifies the SSL socket factory that will be used when performing TLS
682   * negotiation on any new connections created for the purpose of following
683   * referrals.  By default, new pooled connections will use the same socket
684   * factory as the connection on which a referral was received.
685   *
686   * @param  sslSocketFactory
687   *              The SSL socket factory that will be used when performing TLS
688   *              negotiation on any new connections created for the purpose of
689   *              following referrals.  It may be {@code null} if new pooled
690   *              connections should use the same socket factory as the
691   *              connection on which a referral was received.
692   */
693  public void setSSLSocketFactory(
694                   @Nullable final SSLSocketFactory sslSocketFactory)
695  {
696    this.sslSocketFactory = sslSocketFactory;
697  }
698
699
700
701  /**
702   * Retrieves the interval duration in milliseconds that the
703   * {@link PooledReferralConnectorBackgroundThread} should use when sleeping
704   * between checks to determine if any of the established referral connection
705   * pools should be closed.  This is only intended for internal use.  By
706   * default, the interval duration will be 10 seconds (10,000 milliseconds).
707   *
708   * @return  The interval duration in milliseconds that the
709   *          {@code PooledReferralConnectorBackgroundThread} should use when
710   *          sleeping between checks.
711   */
712  long getBackgroundThreadCheckIntervalMillis()
713  {
714    return backgroundThreadCheckIntervalMillis;
715  }
716
717
718
719  /**
720   * Specifies the interval duration in milliseconds that the
721   * {@link PooledReferralConnectorBackgroundThread} should use when sleeping
722   * between checks to determine if any of the established referral connection
723   * pools should be closed.  This is only intended for internal use.  By
724   * default, the interval duration will be 10 seconds (10,000 milliseconds).
725   *
726   * @param  backgroundThreadCheckIntervalMillis
727   *              The interval duration in milliseconds that the
728   *              {@code PooledReferralConnectorBackgroundThread} should use
729   *              when sleeping between checks.  The value must be greater than
730   *              zero.
731   */
732  void setBackgroundThreadCheckIntervalMillis(
733            final long backgroundThreadCheckIntervalMillis)
734  {
735    this.backgroundThreadCheckIntervalMillis =
736         backgroundThreadCheckIntervalMillis;
737  }
738
739
740
741  /**
742   * Retrieves a string representation of the pooled referral connector
743   * properties.
744   *
745   * @return  A string representation of the pooled referral connector
746   *          properties.
747   */
748  @Override()
749  @NotNull()
750  public String toString()
751  {
752    final StringBuilder buffer = new StringBuilder();
753    toString(buffer);
754    return buffer.toString();
755  }
756
757
758
759  /**
760   * Appends a string representation of the pooled referral connector properties
761   * to the provided buffer.
762   *
763   * @param  buffer
764   *              The buffer to which the string representation should be
765   *              appended.  It must not be {@code null}.
766   */
767  public void toString(@NotNull final StringBuilder buffer)
768  {
769    buffer.append("PooledReferralConnectionProperties(" +
770         "initialConnectionsPerPool=");
771    buffer.append(initialConnectionsPerPool);
772    buffer.append(", maximumConnectionsPerPool=");
773    buffer.append(maximumConnectionsPerPool);
774    buffer.append(", retryFailedOperationsDueToInvalidConnections=");
775    buffer.append(retryFailedOperationsDueToInvalidConnections);
776    buffer.append(", maximumConnectionAgeMillis=");
777    buffer.append(maximumConnectionAgeMillis);
778    buffer.append(", maximumPoolAgeMillis=");
779    buffer.append(maximumPoolAgeMillis);
780    buffer.append(", maximumPoolIdleDurationMillis=");
781    buffer.append(maximumPoolIdleDurationMillis);
782    buffer.append(", maximumPoolIdleDurationMillis=");
783    buffer.append(maximumPoolIdleDurationMillis);
784    buffer.append(", healthCheck=");
785    buffer.append(healthCheck);
786    buffer.append(", healthCheckIntervalMillis=");
787    buffer.append(healthCheckIntervalMillis);
788    buffer.append(", bindRequest=");
789    buffer.append(bindRequest);
790    buffer.append(", connectionOptions=");
791    buffer.append(connectionOptions);
792    buffer.append(", ldapURLSecurityType=");
793    buffer.append(ldapURLSecurityType);
794    buffer.append(", sslSocketFactory=");
795    buffer.append(sslSocketFactory);
796    buffer.append(')');
797  }
798}