001/*
002 * Copyright 2007-2018 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2008-2018 Ping Identity Corporation
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021package com.unboundid.ldap.sdk;
022
023
024
025import java.util.Arrays;
026import java.util.Collections;
027import java.util.EnumMap;
028import java.util.HashMap;
029import java.util.Map;
030import java.util.logging.Level;
031
032import com.unboundid.ldap.sdk.extensions.PasswordModifyExtendedRequest;
033import com.unboundid.ldap.sdk.extensions.StartTLSExtendedRequest;
034import com.unboundid.ldap.sdk.extensions.WhoAmIExtendedRequest;
035import com.unboundid.ldap.sdk.unboundidds.extensions.
036            DeregisterYubiKeyOTPDeviceExtendedRequest;
037import com.unboundid.ldap.sdk.unboundidds.extensions.
038            EndAdministrativeSessionExtendedRequest;
039import com.unboundid.ldap.sdk.unboundidds.extensions.
040            GenerateTOTPSharedSecretExtendedRequest;
041import com.unboundid.ldap.sdk.unboundidds.extensions.
042            GetConnectionIDExtendedRequest;
043import com.unboundid.ldap.sdk.unboundidds.extensions.
044            GetPasswordQualityRequirementsExtendedRequest;
045import com.unboundid.ldap.sdk.unboundidds.extensions.
046            PasswordPolicyStateExtendedRequest;
047import com.unboundid.ldap.sdk.unboundidds.extensions.
048            RegisterYubiKeyOTPDeviceExtendedRequest;
049import com.unboundid.ldap.sdk.unboundidds.extensions.
050            RevokeTOTPSharedSecretExtendedRequest;
051import com.unboundid.ldap.sdk.unboundidds.extensions.
052            StartAdministrativeSessionExtendedRequest;
053import com.unboundid.ldap.sdk.unboundidds.extensions.
054            ValidateTOTPPasswordExtendedRequest;
055import com.unboundid.util.Debug;
056import com.unboundid.util.DebugType;
057import com.unboundid.util.Mutable;
058import com.unboundid.util.StaticUtils;
059import com.unboundid.util.ThreadSafety;
060import com.unboundid.util.ThreadSafetyLevel;
061import com.unboundid.util.ssl.SSLSocketVerifier;
062import com.unboundid.util.ssl.TrustAllSSLSocketVerifier;
063
064import static com.unboundid.util.Validator.*;
065
066
067
068/**
069 * This class provides a data structure that may be used to configure a number
070 * of connection-related properties.  Elements included in the set of connection
071 * options include:
072 * <UL>
073 *   <LI>A flag that indicates whether the SDK should attempt to automatically
074 *       re-establish a connection if it is unexpectedly closed.  By default,
075 *       it will not attempt to do so.</LI>
076 *   <LI>A flag that indicates whether simple bind attempts that contain a
077 *       non-empty DN will be required to have a non-empty password.  By
078 *       default, a password will be required in such cases.</LI>
079 *   <LI>A flag that indicates whether to automatically attempt to follow any
080 *       referrals that may be returned by the server.  By default, it will not
081 *       automatically attempt to follow referrals.</LI>
082 *   <LI>A referral hop limit, which indicates the maximum number of hops that
083 *       the connection may take when trying to follow a referral.  The default
084 *       referral hop limit is five.</LI>
085 *   <LI>The referral connector that should be used to create and optionally
086 *       authenticate connections used to follow referrals encountered during
087 *       processing.  By default, referral connections will use the same socket
088 *       factory and bind request as the client connection on which the referral
089 *       was received.</LI>
090 *   <LI>A flag that indicates whether to use the SO_KEEPALIVE socket option to
091 *       attempt to more quickly detect when idle TCP connections have been lost
092 *       or to prevent them from being unexpectedly closed by intermediate
093 *       network hardware.  By default, the SO_KEEPALIVE socket option will be
094 *       used.</LI>
095 *   <LI>A flag that indicates whether to use the SO_LINGER socket option to
096 *       indicate how long a connection should linger after it has been closed,
097 *       and a value that specifies the length of time that it should linger.
098 *       By default, the SO_LINGER option will be used with a timeout of 5
099 *       seconds.</LI>
100 *   <LI>A flag that indicates whether to use the SO_REUSEADDR socket option to
101 *       indicate that a socket in a TIME_WAIT state may be reused.  By default,
102 *       the SO_REUSEADDR socket option will be used.</LI>
103 *   <LI>A flag that indicates whether to operate in synchronous mode, in which
104 *       connections may exhibit better performance and will not require a
105 *       separate reader thread, but will not allow multiple concurrent
106 *       operations to be used on the same connection.</LI>
107 *   <LI>A flag that indicates whether to use the TCP_NODELAY socket option to
108 *       indicate that any data written to the socket will be sent immediately
109 *       rather than delaying for a short amount of time to see if any more data
110 *       is to be sent that could potentially be included in the same packet.
111 *       By default, the TCP_NODELAY socket option will be used.</LI>
112 *   <LI>A value that specifies the maximum length of time in milliseconds that
113 *       an attempt to establish a connection should be allowed to block before
114 *       failing.  By default, a timeout of 10,000 milliseconds (10 seconds)
115 *       will be used.</LI>
116 *   <LI>A value that specifies the default timeout in milliseconds that the SDK
117 *       should wait for a response from the server before failing.  This can be
118 *       defined on a per-operation-type basis, with a default of 300,000
119 *       milliseconds (5 minutes) for search and extended operations, and a
120 *       default timeout of 30,000 milliseconds (30 seconds) for all other types
121 *       of operations.  Further, the extended operation timeout can be
122 *       customized on a per-operation-type basis, and a number of extended
123 *       operation types have been configured with a 30,000 millisecond timeout
124 *       by default.  Individual requests can also be configured with their own
125 *       response timeouts, and if provided, that timeout will override the
126 *       default timeout from the connection options.</LI>
127 *   <LI>A flag that indicates whether to attempt to abandon any request for
128 *       which no response is received after waiting for the maximum response
129 *       timeout.  By default, no abandon request will be sent.</LI>
130 *   <LI>A value which specifies the largest LDAP message size that the SDK will
131 *       be willing to read from the directory server.  By default, the SDK will
132 *       not allow responses larger than 20,971,520 bytes (20MB).  If it
133 *       encounters a message that may be larger than the maximum allowed
134 *       message size, then the SDK will terminate the connection to the
135 *       server.</LI>
136 *   <LI>The {@link DisconnectHandler} that should be used to receive
137 *       notification if connection is disconnected for any reason.  By default,
138 *       no {@code DisconnectHandler} will be used.</LI>
139 *   <LI>The {@link UnsolicitedNotificationHandler} that should be used to
140 *       receive notification about any unsolicited notifications returned by
141 *       the server.  By default, no {@code UnsolicitedNotificationHandler} will
142 *       be used.</LI>
143 *   <LI>A flag that indicates whether to capture a thread stack trace whenever
144 *       a new connection is established.  Capturing a thread stack trace when
145 *       establishing a connection may be marginally expensive, but can be
146 *       useful for debugging certain kinds of problems like leaked connections
147 *       (connections that are established but never explicitly closed).  By
148 *       default, connect stack traces will not be captured.</LI>
149 *   <LI>A flag that indicates whether connections should try to retrieve schema
150 *       information from the server, which may be used to better determine
151 *       which matching rules should be used when comparing attribute values.
152 *       By default, server schema information will not be retrieved.</LI>
153 *   <LI>The size of the socket receive buffer, which may be used for
154 *       temporarily holding data received from the directory server until it
155 *       can be read and processed by the LDAP SDK.  By default, the receive
156 *       buffer size will be automatically determined by the JVM based on the
157 *       underlying system settings.</LI>
158 *   <LI>The size of the socket send buffer, which may be used for temporarily
159 *       holding data to be sent to the directory server until it can actually
160 *       be transmitted over the network.  By default, the send buffer size will
161 *       be automatically determined by the JVM based on the underlying system
162 *       settings.</LI>
163 *  <LI>A flag which indicates whether to allow a single socket factory instance
164 *      (which may be shared across multiple connections) to be used to create
165 *      multiple concurrent connections.  This offers better and more
166 *      predictable performance on some JVM implementations (especially when
167 *      connection attempts fail as a result of a connection timeout), but some
168 *      JVMs are known to use non-threadsafe socket factory implementations and
169 *      may fail from concurrent use (for example, at least some IBM JVMs
170 *      exhibit this behavior).  By default, Sun/Oracle JVMs will allow
171 *      concurrent socket factory use, but JVMs from other vendors will use
172 *      synchronization to ensure that a socket factory will only be allowed to
173 *      create one connection at a time.</LI>
174 *  <LI>A class that may be used to perform additional verification (e.g.,
175 *      hostname validation) for any {@code SSLSocket} instances created.  By
176 *      default, no special verification will be performed.</LI>
177 * </UL>
178 */
179@Mutable()
180@ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE)
181public final class LDAPConnectionOptions
182{
183  /**
184   * The prefix that will be used in conjunction with all system properties.
185   */
186  private static final String PROPERTY_PREFIX =
187       LDAPConnectionOptions.class.getName() + '.';
188
189
190
191  /**
192   * The name of a system property that can be used to specify the initial
193   * default value for the "abandon on timeout" behavior.  If this property is
194   * set at the time that this class is loaded, then its value must be either
195   * "true" or "false".  If this property is not set, then a default value of
196   * "false" will be assumed.
197   * <BR><BR>
198   * The full name for this system property is
199   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultAbandonTimeout".
200   */
201  public static final String PROPERTY_DEFAULT_ABANDON_ON_TIMEOUT =
202       PROPERTY_PREFIX + "defaultAbandonOnTimeout";
203
204
205
206  /**
207   * The default value for the setting that controls whether to automatically
208   * attempt to abandon any request for which no response is received within the
209   * maximum response timeout.  If the
210   * {@link #PROPERTY_DEFAULT_ABANDON_ON_TIMEOUT} system property is set at the
211   * time this class is loaded, then its value will be used.  Otherwise, a
212   * default of {@code false} will be used.
213   */
214  private static final boolean DEFAULT_ABANDON_ON_TIMEOUT =
215       getSystemProperty(PROPERTY_DEFAULT_ABANDON_ON_TIMEOUT, false);
216
217
218
219  /**
220   * The default value ({@code false}) for the setting that controls whether to
221   * automatically attempt to reconnect if a connection is unexpectedly lost.
222   */
223  private static final boolean DEFAULT_AUTO_RECONNECT = false;
224
225
226
227  /**
228   * The name of a system property that can be used to specify the initial
229   * default value for the "bind with DN requires password" behavior.  If this
230   * property is set at the time that this class is loaded, then its value must
231   * be either "true" or "false".  If this property is not set, then a default
232   * value of "true" will be assumed.
233   * <BR><BR>
234   * The full name for this system property is
235   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.
236   * defaultBindWithDNRequiresPassword".
237   */
238  public static final String PROPERTY_DEFAULT_BIND_WITH_DN_REQUIRES_PASSWORD =
239       PROPERTY_PREFIX + "defaultBindWithDNRequiresPassword";
240
241
242
243  /**
244   * The default value for the setting that controls whether simple bind
245   * requests with a DN will also be required to contain a password.  If the
246   * {@link #PROPERTY_DEFAULT_BIND_WITH_DN_REQUIRES_PASSWORD} system property is
247   * set at the time this class is loaded, then its value will be used.
248   * Otherwise, a default of {@code true} will be used.
249   */
250  private static final boolean DEFAULT_BIND_WITH_DN_REQUIRES_PASSWORD =
251       getSystemProperty(PROPERTY_DEFAULT_BIND_WITH_DN_REQUIRES_PASSWORD, true);
252
253
254
255  /**
256   * The name of a system property that can be used to specify the initial
257   * default value for the "capture connect stack trace" behavior.  If this
258   * property is set at the time that this class is loaded, then its value must
259   * be either "true" or "false".  If this property is not set, then a default
260   * value of "false" will be assumed.
261   * <BR><BR>
262   * The full name for this system property is "com.unboundid.ldap.sdk.
263   * LDAPConnectionOptions.defaultCaptureConnectStackTrace".
264   */
265  public static final String PROPERTY_DEFAULT_CAPTURE_CONNECT_STACK_TRACE =
266       PROPERTY_PREFIX + "defaultCaptureConnectStackTrace";
267
268
269
270  /**
271   * The default value for the setting that controls whether to capture a thread
272   * stack trace whenever an attempt is made to establish a connection.  If the
273   * {@link #PROPERTY_DEFAULT_CAPTURE_CONNECT_STACK_TRACE} system property is
274   * set at the time this class is loaded, then its value will be used.
275   * Otherwise, a default of {@code false} will be used.
276   */
277  private static final boolean DEFAULT_CAPTURE_CONNECT_STACK_TRACE =
278       getSystemProperty(PROPERTY_DEFAULT_CAPTURE_CONNECT_STACK_TRACE, false);
279
280
281
282  /**
283   * The name of a system property that can be used to specify the initial
284   * default value for the "follow referrals" behavior.  If this property is set
285   * at the time that this class is loaded, then its value must be either
286   * "true" or "false".  If this property is not set, then a default value of
287   * "false" will be assumed.
288   * <BR><BR>
289   * The full name for this system property is
290   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultFollowReferrals".
291   */
292  public static final String PROPERTY_DEFAULT_FOLLOW_REFERRALS =
293       PROPERTY_PREFIX + "defaultFollowReferrals";
294
295
296
297  /**
298   * The default value for the setting that controls whether to attempt to
299   * automatically follow referrals.  If the
300   * {@link #PROPERTY_DEFAULT_FOLLOW_REFERRALS} system property is set at the
301   * time this class is loaded, then its value will be used.  Otherwise, a
302   * default of {@code false} will be used.
303   */
304  private static final boolean DEFAULT_FOLLOW_REFERRALS =
305       getSystemProperty(PROPERTY_DEFAULT_FOLLOW_REFERRALS, false);
306
307
308
309  /**
310   * The name of a system property that can be used to specify the maximum
311   * number of hops to make when following a referral.  If this property is set
312   * at the time that this class is loaded, then its value must be parseable as
313   * an integer.  If this property is not set, then a default value of "5" will
314   * be assumed.
315   * <BR><BR>
316   * The full name for this system property is
317   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultReferralHopLimit".
318   */
319  public static final String PROPERTY_DEFAULT_REFERRAL_HOP_LIMIT =
320       PROPERTY_PREFIX + "defaultReferralHopLimit";
321
322
323
324  /**
325   * The default value for the setting that controls the referral hop limit.  If
326   * the {@link #PROPERTY_DEFAULT_REFERRAL_HOP_LIMIT} system property is set at
327   * the time this class is loaded, then its value will be used.  Otherwise, a
328   * default value of 5 will be used.
329   */
330  private static final int DEFAULT_REFERRAL_HOP_LIMIT =
331       getSystemProperty(PROPERTY_DEFAULT_REFERRAL_HOP_LIMIT, 5);
332
333
334
335  /**
336   * The name of a system property that can be used to specify the initial
337   * default value for the "use schema" behavior.  If this property is set at
338   * the time that this class is loaded, then its value must be either "true" or
339   * "false".  If this property is not set, then a default value of "false" will
340   * be assumed.
341   * <BR><BR>
342   * The full name for this system property is
343   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseSchema".
344   */
345  public static final String PROPERTY_DEFAULT_USE_SCHEMA =
346       PROPERTY_PREFIX + "defaultUseSchema";
347
348
349
350  /**
351   * The default value for the setting that controls whether to use schema when
352   * reading data from the server.  If the {@link #PROPERTY_DEFAULT_USE_SCHEMA}
353   * system property is set at the time this class is loaded, then its value
354   * will be used.  Otherwise, a default value of {@code false} will be used.
355   */
356  private static final boolean DEFAULT_USE_SCHEMA =
357       getSystemProperty(PROPERTY_DEFAULT_USE_SCHEMA, false);
358
359
360
361  /**
362   * The name of a system property that can be used to specify the initial
363   * default value for the "use pooled schema" behavior.  If this property is
364   * set at the time that this class is loaded, then its value must be either
365   * "true" or "false".  If this property is not set, then a default value of
366   * "false" will be assumed.
367   * <BR><BR>
368   * The full name for this system property is
369   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUsePooledSchema".
370   */
371  public static final String PROPERTY_DEFAULT_USE_POOLED_SCHEMA =
372       PROPERTY_PREFIX + "defaultUsePooledSchema";
373
374
375
376  /**
377   * The default value for the setting that controls whether all connections in
378   * a connection pool should use the same cached schema object.  If the
379   * {@link #PROPERTY_DEFAULT_USE_POOLED_SCHEMA} system property is set at the
380   * time this class is loaded, then its value will be used.  Otherwise, a
381   * default of {@code false} will be used.
382   */
383  private static final boolean DEFAULT_USE_POOLED_SCHEMA =
384       getSystemProperty(PROPERTY_DEFAULT_USE_POOLED_SCHEMA, false);
385
386
387
388  /**
389   * The name of a system property that can be used to specify the initial
390   * default value for the pooled schema timeout, in milliseconds.  If this
391   * property is set at the time that this class is loaded, then its value must
392   * be parseable as an integer.  If this property is not set, then a default
393   * value of "3600000" (3,600,000 milliseconds, or 1 hour) will be assumed.
394   * <BR><BR>
395   * The full name for this system property is "com.unboundid.ldap.sdk.
396   * LDAPConnectionOptions.defaultPooledSchemaTimeoutMillis".
397   */
398  public static final String PROPERTY_DEFAULT_POOLED_SCHEMA_TIMEOUT_MILLIS =
399       PROPERTY_PREFIX + "defaultPooledSchemaTimeoutMillis";
400
401
402
403  /**
404   * The default value for the setting that controls the default pooled schema
405   * timeout.  If the {@link #PROPERTY_DEFAULT_POOLED_SCHEMA_TIMEOUT_MILLIS}
406   * system property is set at the time this class is loaded, then its value
407   * will be used.  Otherwise, a default of 3,600,000 milliseconds (1 hour) will
408   * be used.
409   */
410  private static final long DEFAULT_POOLED_SCHEMA_TIMEOUT_MILLIS = 3_600_000L;
411
412
413
414  /**
415   * The name of a system property that can be used to specify the initial
416   * default value for the "use keepalive" behavior.  If this property is set at
417   * the time that this class is loaded, then its value must be either "true" or
418   * "false".  If this property is not set, then a default value of "true" will
419   * be assumed.
420   * <BR><BR>
421   * The full name for this system property is
422   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseKeepalive".
423   */
424  public static final String PROPERTY_DEFAULT_USE_KEEPALIVE =
425       PROPERTY_PREFIX + "defaultUseKeepalive";
426
427
428
429  /**
430   * The default value for the setting that controls whether to use the
431   * {@code SO_KEEPALIVE} socket option.  If the
432   * {@link #PROPERTY_DEFAULT_USE_KEEPALIVE} system property is set at the time
433   * this class is loaded, then its value will be used.  Otherwise, a default of
434   * {@code true} will be used.
435   */
436  private static final boolean DEFAULT_USE_KEEPALIVE =
437       getSystemProperty(PROPERTY_DEFAULT_USE_KEEPALIVE, true);
438
439
440
441  /**
442   * The name of a system property that can be used to specify the initial
443   * default value for the "use linger" behavior.  If this property is set at
444   * the time that this class is loaded, then its value must be either "true" or
445   * "false".  If this property is not set, then a default value of "true" will
446   * be assumed.
447   * <BR><BR>
448   * The full name for this system property is
449   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseLinger".
450   */
451  public static final String PROPERTY_DEFAULT_USE_LINGER =
452       PROPERTY_PREFIX + "defaultUseLinger";
453
454
455
456  /**
457   * The default value for the setting that controls whether to use the
458   * {@code SO_LINGER} socket option.  If the
459   * {@link #PROPERTY_DEFAULT_USE_LINGER} system property is set at the time
460   * this class is loaded, then its value will be used.  Otherwise, a default of
461   * {@code true} will be used.
462   */
463  private static final boolean DEFAULT_USE_LINGER =
464       getSystemProperty(PROPERTY_DEFAULT_USE_LINGER, true);
465
466
467
468  /**
469   * The name of a system property that can be used to specify the initial
470   * default value for the linger timeout, in seconds.  If this property is set
471   * at the time that this class is loaded, then its value must be parseable as
472   * an integer.  If this property is not set, then a default value of "5" (5
473   * seconds) will be assumed.
474   * <BR><BR>
475   * The full name for this system property is
476   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultLingerTimeoutSeconds".
477   */
478  public static final String PROPERTY_DEFAULT_LINGER_TIMEOUT_SECONDS =
479       PROPERTY_PREFIX + "defaultLingerTimeoutSeconds";
480
481
482
483  /**
484   * The default value for the setting that controls the timeout in seconds that
485   * will be used with the {@code SO_LINGER} socket option.  If the
486   * {@link #PROPERTY_DEFAULT_LINGER_TIMEOUT_SECONDS} property is set at the
487   * time this class is loaded, then its value will be used.  Otherwise, a
488   * default linger timeout of 5 seconds will be used.
489   */
490  private static final int DEFAULT_LINGER_TIMEOUT_SECONDS =
491       getSystemProperty(PROPERTY_DEFAULT_LINGER_TIMEOUT_SECONDS, 5);
492
493
494
495  /**
496   * The name of a system property that can be used to specify the initial
497   * default value for the "use reuse address" behavior.  If this property is
498   * set at the time that this class is loaded, then its value must be either
499   * "true" or "false".  If this property is not set, then a default value of
500   * "true" will be assumed.
501   * <BR><BR>
502   * The full name for this system property is
503   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseReuseAddress".
504   */
505  public static final String PROPERTY_DEFAULT_USE_REUSE_ADDRESS =
506       PROPERTY_PREFIX + "defaultUseReuseAddress";
507
508
509
510  /**
511   * The default value for the setting that controls whether to use the
512   * {@code SO_REUSEADDR} socket option.  If the
513   * {@link #PROPERTY_DEFAULT_USE_REUSE_ADDRESS} system property is set at the
514   * time this class is loaded, then its value will be used.  Otherwise, a
515   * default value of {@code true} will be used.
516   */
517  private static final boolean DEFAULT_USE_REUSE_ADDRESS =
518       getSystemProperty(PROPERTY_DEFAULT_USE_REUSE_ADDRESS, true);
519
520
521
522  /**
523   * The name of a system property that can be used to specify the initial
524   * default value for the "use synchronous mode" behavior.  If this property is
525   * set at the time that this class is loaded, then its value must be either
526   * "true" or "false".  If this property is not set, then a default value of
527   * "false" will be assumed.
528   * <BR><BR>
529   * The full name for this system property is
530   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseSynchronousMode".
531   */
532  public static final String PROPERTY_DEFAULT_USE_SYNCHRONOUS_MODE =
533       PROPERTY_PREFIX + "defaultUseSynchronousMode";
534
535
536
537  /**
538   * The default value for the setting that controls whether to operate in
539   * synchronous mode, in which only a single outstanding operation may be in
540   * progress on an associated connection at any given time.  If the
541   * {@link #PROPERTY_DEFAULT_USE_SYNCHRONOUS_MODE} system property is set at
542   * the time this class is loaded, then its value will be used.  Otherwise, a
543   * default value of {@code false} will be used.
544   */
545  private static final boolean DEFAULT_USE_SYNCHRONOUS_MODE =
546       getSystemProperty(PROPERTY_DEFAULT_USE_SYNCHRONOUS_MODE, false);
547
548
549
550  /**
551   * The name of a system property that can be used to specify the initial
552   * default value for the "use TCP nodelay" behavior.  If this property is set
553   * at the time that this class is loaded, then its value must be either "true"
554   * or "false".  If this property is not set, then a default value of "true"
555   * will be assumed.
556   * <BR><BR>
557   * The full name for this system property is
558   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseTCPNoDelay".
559   */
560  public static final String PROPERTY_DEFAULT_USE_TCP_NODELAY =
561       PROPERTY_PREFIX + "defaultUseTCPNoDelay";
562
563
564
565  /**
566   * The default value for the setting that controls whether to use the
567   * {@code TCP_NODELAY} socket option.  If the
568   * {@link #PROPERTY_DEFAULT_USE_TCP_NODELAY} system property is set at the
569   * time this class is loaded, then its value will be used.  Otherwise, a
570   * default value of {@code true} will be used.
571   */
572  private static final boolean DEFAULT_USE_TCP_NODELAY =
573       getSystemProperty(PROPERTY_DEFAULT_USE_TCP_NODELAY, true);
574
575
576
577  /**
578   * The name of a system property that can be used to specify the initial
579   * default connect timeout, in milliseconds.  If this property is set at the
580   * time that this class is loaded, then its value must be parseable as an
581   * integer.  If this property is not set then a default value of "10000"
582   * (10,000 milliseconds, or ten seconds) will be assumed.
583   * <BR><BR>
584   * The full name for this system property is
585   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultConnectTimeoutMillis".
586   */
587  public static final String PROPERTY_DEFAULT_CONNECT_TIMEOUT_MILLIS =
588       PROPERTY_PREFIX + "defaultConnectTimeoutMillis";
589
590
591
592  /**
593   * The default value for the setting that controls the timeout in milliseconds
594   * when trying to establish a new connection.  If the
595   * {@link #PROPERTY_DEFAULT_CONNECT_TIMEOUT_MILLIS} system property is set at
596   * the time this class is loaded, then its value will be used.  Otherwise, a
597   * default of 10,000 milliseconds (10 seconds) will be used.
598   */
599  private static final int DEFAULT_CONNECT_TIMEOUT_MILLIS =
600       getSystemProperty(PROPERTY_DEFAULT_CONNECT_TIMEOUT_MILLIS, 10_000);
601
602
603
604  /**
605   * The name of a system property that can be used to specify the initial
606   * default value for the maximum message size, in bytes.  If this property is
607   * set at the time that this class is loaded, then its value must be parseable
608   * as an integer.  If this property is not set, then a default value of
609   * "20971520" (20 megabytes) will be assumed.
610   * <BR><BR>
611   * The full name for this system property is
612   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultMaxMessageSizeBytes".
613   */
614  public static final String PROPERTY_DEFAULT_MAX_MESSAGE_SIZE_BYTES =
615       PROPERTY_PREFIX + "defaultMaxMessageSizeBytes";
616
617
618
619  /**
620   * The default value for the setting that controls the maximum LDAP message
621   * size in bytes that will be allowed when reading data from a directory
622   * server.  If the {@link #PROPERTY_DEFAULT_MAX_MESSAGE_SIZE_BYTES} system
623   * property is set at the time this class is loaded, then its value will be
624   * used.  Otherwise, a default value of 20,971,520 bytes (20 megabytes) will
625   * be used.
626   */
627  private static final int DEFAULT_MAX_MESSAGE_SIZE_BYTES =
628       getSystemProperty(PROPERTY_DEFAULT_MAX_MESSAGE_SIZE_BYTES, 20_971_520);
629
630
631
632  /**
633   * The name of a system property that can be used to specify the initial
634   * default value for the receive buffer size, in bytes.  If this property is
635   * set at the time that this class is loaded, then its value must be parseable
636   * as an integer.  If this property is not set, then a default value of "0"
637   * (indicating that the JVM's default receive buffer size) will be assumed.
638   * <BR><BR>
639   * The full name for this system property is "com.unboundid.ldap.sdk.
640   * LDAPConnectionOptions.defaultReceiveBufferSizeBytes".
641   */
642  public static final String PROPERTY_DEFAULT_RECEIVE_BUFFER_SIZE_BYTES =
643       PROPERTY_PREFIX + "defaultReceiveBufferSizeBytes";
644
645
646
647  /**
648   * The default size, in bytes, to use for the receive buffer.  If the
649   * {@link #PROPERTY_DEFAULT_RECEIVE_BUFFER_SIZE_BYTES} system property is set
650   * at the time this class is loaded, then its value will be used.  Otherwise,
651   * a default value of 0 will be used to indicate that the JVM's default
652   * receive buffer size should be used.
653   */
654  private static final int DEFAULT_RECEIVE_BUFFER_SIZE_BYTES =
655       getSystemProperty(PROPERTY_DEFAULT_RECEIVE_BUFFER_SIZE_BYTES, 0);
656
657
658
659  /**
660   * The name of a system property that can be used to specify the initial
661   * default value for the send buffer size, in bytes.  If this property is set
662   * at the time that this class is loaded, then its value must be parseable as
663   * an integer.  If this property is not set, then a default value of "0"
664   * (indicating that the JVM's default send buffer size) will be assumed.
665   * <BR><BR>
666   * The full name for this system property is
667   * "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultSendBufferSizeBytes".
668   */
669  public static final String PROPERTY_DEFAULT_SEND_BUFFER_SIZE_BYTES =
670       PROPERTY_PREFIX + "defaultSendBufferSizeBytes";
671
672
673
674  /**
675   * The default size, in bytes, to use for the send buffer.  If the
676   * {@link #PROPERTY_DEFAULT_SEND_BUFFER_SIZE_BYTES} system property is set at
677   * the time this class is loaded, then its value will be used.  Otherwise, a
678   * default value of 0 will be used to indicate that the JVM's default send
679   * buffer size should be used.
680   */
681  private static final int DEFAULT_SEND_BUFFER_SIZE_BYTES =
682       getSystemProperty(PROPERTY_DEFAULT_SEND_BUFFER_SIZE_BYTES, 0);
683
684
685
686  /**
687   * The name of a system property that can be used to specify the initial
688   * default value for response timeouts, in milliseconds, for all types of
689   * operations.  If this property is set at the time that this class is loaded,
690   * then its value must be parseable as an integer, and that value will
691   * override the values of any operation-specific properties.  If this property
692   * is not set, then a default value of "300000" (300,000 milliseconds, or
693   * 5 minutes) will be assumed, but that may be overridden by
694   * operation-specific properties.
695   * <BR><BR>
696   * The full name for this system property is "com.unboundid.ldap.sdk.
697   * LDAPConnectionOptions.defaultResponseTimeoutMillis".
698   */
699  public static final String PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS =
700       PROPERTY_PREFIX + "defaultResponseTimeoutMillis";
701
702
703
704  /**
705   * The name of a system property that can be used to specify the initial
706   * default value for response timeouts, in milliseconds, for add operations.
707   * If this property is set at the time that this class is loaded, then
708   * its value must be parseable as an integer.  It will only be used if the
709   * {@link #PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS} system property is not
710   * set, as that property will override this one.  If neither of those
711   * properties is set, then a default value of "30000" (30,000 milliseconds, or
712   * 30 seconds) will be assumed.
713   * <BR><BR>
714   * The full name for this system property is "com.unboundid.ldap.sdk.
715   * LDAPConnectionOptions.defaultAddResponseTimeoutMillis".
716   */
717  public static final String PROPERTY_DEFAULT_ADD_RESPONSE_TIMEOUT_MILLIS =
718       PROPERTY_PREFIX + "defaultAddResponseTimeoutMillis";
719
720
721
722  /**
723   * The name of a system property that can be used to specify the initial
724   * default value for response timeouts, in milliseconds, for bind operations.
725   * If this property is set at the time that this class is loaded, then
726   * its value must be parseable as an integer.  It will only be used if the
727   * {@link #PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS} system property is not
728   * set, as that property will override this one.  If neither of those
729   * properties is set, then a default value of "30000" (30,000 milliseconds, or
730   * 30 seconds) will be assumed.
731   * <BR><BR>
732   * The full name for this system property is "com.unboundid.ldap.sdk.
733   * LDAPConnectionOptions.defaultBindResponseTimeoutMillis".
734   */
735  public static final String PROPERTY_DEFAULT_BIND_RESPONSE_TIMEOUT_MILLIS =
736       PROPERTY_PREFIX + "defaultBindResponseTimeoutMillis";
737
738
739
740  /**
741   * The name of a system property that can be used to specify the initial
742   * default value for response timeouts, in milliseconds, for compare
743   * operations.  If this property is set at the time that this class is
744   * loaded, then its value must be parseable as an integer.  It will only be
745   * used if the {@link #PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS} system
746   * property is not set, as that property will override this one.  If neither
747   * of those properties is set, then a default value of "30000" (30,000
748   * milliseconds, or 30 seconds) will be assumed.
749   * <BR><BR>
750   * The full name for this system property is "com.unboundid.ldap.sdk.
751   * LDAPConnectionOptions.defaultCompareResponseTimeoutMillis".
752   */
753  public static final String PROPERTY_DEFAULT_COMPARE_RESPONSE_TIMEOUT_MILLIS =
754       PROPERTY_PREFIX + "defaultCompareResponseTimeoutMillis";
755
756
757
758  /**
759   * The name of a system property that can be used to specify the initial
760   * default value for response timeouts, in milliseconds, for delete
761   * operations.  If this property is set at the time that this class is
762   * loaded, then its value must be parseable as an integer.  It will only be
763   * used if the {@link #PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS} system
764   * property is not set, as that property will override this one.  If neither
765   * of those properties is set, then a default value of "30000" (30,000
766   * milliseconds, or 30 seconds) will be assumed.
767   * <BR><BR>
768   * The full name for this system property is "com.unboundid.ldap.sdk.
769   * LDAPConnectionOptions.defaultDeleteResponseTimeoutMillis".
770   */
771  public static final String PROPERTY_DEFAULT_DELETE_RESPONSE_TIMEOUT_MILLIS =
772       PROPERTY_PREFIX + "defaultDeleteResponseTimeoutMillis";
773
774
775
776  /**
777   * The name of a system property that can be used to specify the initial
778   * default value for response timeouts, in milliseconds, for extended
779   * operations.  If this property is set at the time that this class is
780   * loaded, then its value must be parseable as an integer.  It will only be
781   * used if the {@link #PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS} system
782   * property is not set, as that property will override this one.  If neither
783   * of those properties is set, then a default value of "300000" (300,000
784   * milliseconds, or 5 minutes) will be assumed.
785   * <BR><BR>
786   * The full name for this system property is "com.unboundid.ldap.sdk.
787   * LDAPConnectionOptions.defaultExtendedResponseTimeoutMillis".
788   * <BR><BR>
789   * Note that different timeouts may be set for specific types using a system
790   * property with this name immediately followed by a period and the request
791   * OID for the desired extended operation type.  For example, the system
792   * property named "com.unboundid.ldap.sdk.LDAPConnectionOptions.
793   * defaultExtendedResponseTimeoutMillis.1.3.6.1.4.1.1466.20037" can be used to
794   * set a default response timeout for StartTLS extended operations.
795   * <BR><BR>
796   * If neither the {@link #PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS} nor the
797   * {@code PROPERTY_DEFAULT_EXTENDED_RESPONSE_TIMEOUT_MILLIS} property is set,
798   * then the following standard extended operation types will have a default
799   * timeout of 30,000 milliseconds (30 seconds) instead of 300,000 milliseconds
800   * (5 minutes), unless a property is defined to override the timeout for that
801   * specific type of extended operation:
802   * <BR>
803   * <UL>
804   *   <LI>Password Modify (1.3.6.1.4.1.4203.1.11.1)</LI>
805   *   <LI>StartTLS (1.3.6.1.4.1.1466.20037)</LI>
806   *   <LI>Who Am I? (1.3.6.1.4.1.4203.1.11.3)</LI>
807   * </UL>
808   * <BR>
809   * The same will also be true for the following extended operations specific
810   * to the UnboundID/Ping Identity Directory Server:
811   * <BR>
812   * <UL>
813   *   <LI>Deregister YubiKey OTP Device (1.3.6.1.4.1.30221.2.6.55)</LI>
814   *   <LI>End Administrative Session (1.3.6.1.4.1.30221.2.6.14)</LI>
815   *   <LI>Generate TOTP Shared Secret (1.3.6.1.4.1.30221.2.6.56)</LI>
816   *   <LI>Get Connection ID (1.3.6.1.4.1.30221.1.6.2)</LI>
817   *   <LI>Get Password Quality Requirements (1.3.6.1.4.1.30221.2.6.43)</LI>
818   *   <LI>Password Policy State (1.3.6.1.4.1.30221.1.6.1)</LI>
819   *   <LI>Register YubiKey OTP Device (1.3.6.1.4.1.30221.2.6.54)</LI>
820   *   <LI>Revoke TOTP Shared Secret (1.3.6.1.4.1.30221.2.6.58)</LI>
821   *   <LI>Start Administrative Session (1.3.6.1.4.1.30221.2.6.13)</LI>
822   *   <LI>Validate TOTP Password (1.3.6.1.4.1.30221.2.6.15)</LI>
823   * </UL>
824   */
825  public static final String PROPERTY_DEFAULT_EXTENDED_RESPONSE_TIMEOUT_MILLIS =
826       PROPERTY_PREFIX + "defaultExtendedResponseTimeoutMillis";
827
828
829
830  /**
831   * The name of a system property that can be used to specify the initial
832   * default value for response timeouts, in milliseconds, for modify
833   * operations.  If this property is set at the time that this class is
834   * loaded, then its value must be parseable as an integer.  It will only be
835   * used if the {@link #PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS} system
836   * property is not set, as that property will override this one.  If neither
837   * of those properties is set, then a default value of "30000" (30,000
838   * milliseconds, or 30 seconds) will be assumed.
839   * <BR><BR>
840   * The full name for this system property is "com.unboundid.ldap.sdk.
841   * LDAPConnectionOptions.defaultModifyResponseTimeoutMillis".
842   */
843  public static final String PROPERTY_DEFAULT_MODIFY_RESPONSE_TIMEOUT_MILLIS =
844       PROPERTY_PREFIX + "defaultModifyResponseTimeoutMillis";
845
846
847
848  /**
849   * The name of a system property that can be used to specify the initial
850   * default value for response timeouts, in milliseconds, for modify DN
851   * operations.  If this property is set at the time that this class is
852   * loaded, then its value must be parseable as an integer.  It will only be
853   * used if the {@link #PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS} system
854   * property is not set, as that property will override this one.  If neither
855   * of those properties is set, then a default value of "30000" (30,000
856   * milliseconds, or 30 seconds) will be assumed.
857   * <BR><BR>
858   * The full name for this system property is "com.unboundid.ldap.sdk.
859   * LDAPConnectionOptions.defaultModifyDNResponseTimeoutMillis".
860   */
861  public static final String
862       PROPERTY_DEFAULT_MODIFY_DN_RESPONSE_TIMEOUT_MILLIS =
863            PROPERTY_PREFIX + "defaultModifyDNResponseTimeoutMillis";
864
865
866
867  /**
868   * The name of a system property that can be used to specify the initial
869   * default value for response timeouts, in milliseconds, for search
870   * operations.  If this property is set at the time that this class is
871   * loaded, then its value must be parseable as an integer.  It will only be
872   * used if the {@link #PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS} system
873   * property is not set, as that property will override this one.  If neither
874   * of those properties is set, then a default value of "300000" (300,000
875   * milliseconds, or 5 minutes) will be assumed.
876   * <BR><BR>
877   * The full name for this system property is "com.unboundid.ldap.sdk.
878   * LDAPConnectionOptions.defaultSearchResponseTimeoutMillis".
879   */
880  public static final String PROPERTY_DEFAULT_SEARCH_RESPONSE_TIMEOUT_MILLIS =
881       PROPERTY_PREFIX + "defaultSearchResponseTimeoutMillis";
882
883
884
885  /**
886   * The default value for the setting that controls the default response
887   * timeout, in milliseconds, for all types of operations.
888   */
889  private static final long DEFAULT_RESPONSE_TIMEOUT_MILLIS;
890
891
892
893  /**
894   * A map that holds the default values for the settings that control the
895   * default response timeouts, in milliseconds, for each type of operation.
896   */
897  private static final Map<OperationType,Long>
898       DEFAULT_RESPONSE_TIMEOUT_MILLIS_BY_OPERATION_TYPE;
899
900
901
902  /**
903   * A map that holds the default values for the settings that control the
904   * default response timeouts, in milliseconds, for specific types of extended
905   * operations.
906   */
907  private static final Map<String,Long>
908       DEFAULT_RESPONSE_TIMEOUT_MILLIS_BY_EXTENDED_OPERATION_TYPE;
909
910
911
912  static
913  {
914    Long allOpsTimeout = null;
915    final EnumMap<OperationType,Long> timeoutsByOpType =
916         new EnumMap<>(OperationType.class);
917    final HashMap<String,Long> timeoutsByExtOpType = new HashMap<>(10);
918
919    final String allOpsPropertyValue =
920         System.getProperty(PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS);
921    if (allOpsPropertyValue != null)
922    {
923      try
924      {
925        allOpsTimeout = Math.max(0L, Long.parseLong(allOpsPropertyValue));
926        for (final OperationType ot : OperationType.values())
927        {
928          timeoutsByOpType.put(ot, allOpsTimeout);
929        }
930
931        if (Debug.debugEnabled())
932        {
933          Debug.debug(Level.INFO, DebugType.OTHER,
934               "Using value " + allOpsTimeout + " set for system property '" +
935                  PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS + "'.  This " +
936                    "timeout will be used for all operation types.");
937        }
938      }
939      catch (final Exception e)
940      {
941        if (Debug.debugEnabled())
942        {
943          Debug.debugException(e);
944          Debug.debug(Level.WARNING, DebugType.OTHER,
945               "Invalid value '" + allOpsPropertyValue + "' set for system " +
946                    "property '" + PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS +
947                    "'.  The value was expected to be a long.  Ignoring " +
948                    "this property and proceeding as if it had not been set.");
949        }
950      }
951    }
952
953    if (allOpsTimeout == null)
954    {
955      allOpsTimeout = 300_000L;
956
957      // Use hard-coded response timeouts of 10 seconds for abandon and unbind
958      // operations.  There is no response for these operations, but the timeout
959      // is also used for sending the request.
960      timeoutsByOpType.put(OperationType.ABANDON, 10_000L);
961      timeoutsByOpType.put(OperationType.UNBIND, 10_000L);
962
963      timeoutsByOpType.put(OperationType.ADD,
964           getSystemProperty(PROPERTY_DEFAULT_ADD_RESPONSE_TIMEOUT_MILLIS,
965                30_000L));
966      timeoutsByOpType.put(OperationType.BIND,
967           getSystemProperty(PROPERTY_DEFAULT_BIND_RESPONSE_TIMEOUT_MILLIS,
968                30_000L));
969      timeoutsByOpType.put(OperationType.COMPARE,
970           getSystemProperty(PROPERTY_DEFAULT_COMPARE_RESPONSE_TIMEOUT_MILLIS,
971                30_000L));
972      timeoutsByOpType.put(OperationType.DELETE,
973           getSystemProperty(PROPERTY_DEFAULT_DELETE_RESPONSE_TIMEOUT_MILLIS,
974                30_000L));
975      timeoutsByOpType.put(OperationType.MODIFY,
976           getSystemProperty(PROPERTY_DEFAULT_MODIFY_RESPONSE_TIMEOUT_MILLIS,
977                30_000L));
978      timeoutsByOpType.put(OperationType.MODIFY_DN,
979           getSystemProperty(PROPERTY_DEFAULT_MODIFY_DN_RESPONSE_TIMEOUT_MILLIS,
980                30_000L));
981      timeoutsByOpType.put(OperationType.SEARCH,
982           getSystemProperty(PROPERTY_DEFAULT_SEARCH_RESPONSE_TIMEOUT_MILLIS,
983                300_000L));
984
985      final String extendedOperationTypePrefix =
986           PROPERTY_DEFAULT_EXTENDED_RESPONSE_TIMEOUT_MILLIS + '.';
987      for (final String propertyName :
988           System.getProperties().stringPropertyNames())
989      {
990        if (propertyName.startsWith(extendedOperationTypePrefix))
991        {
992          final Long value = getSystemProperty(propertyName, null);
993          if (value != null)
994          {
995            final String oid = propertyName.substring(
996                 extendedOperationTypePrefix.length());
997            timeoutsByExtOpType.put(oid, value);
998          }
999        }
1000      }
1001
1002      final Long extendedOpTimeout = getSystemProperty(
1003           PROPERTY_DEFAULT_EXTENDED_RESPONSE_TIMEOUT_MILLIS, null);
1004      if (extendedOpTimeout == null)
1005      {
1006        timeoutsByOpType.put(OperationType.EXTENDED, 300_000L);
1007
1008        for (final String oid :
1009          Arrays.asList(
1010               PasswordModifyExtendedRequest.PASSWORD_MODIFY_REQUEST_OID,
1011               StartTLSExtendedRequest.STARTTLS_REQUEST_OID,
1012               WhoAmIExtendedRequest.WHO_AM_I_REQUEST_OID,
1013               DeregisterYubiKeyOTPDeviceExtendedRequest.
1014                    DEREGISTER_YUBIKEY_OTP_DEVICE_REQUEST_OID,
1015               EndAdministrativeSessionExtendedRequest.
1016                    END_ADMIN_SESSION_REQUEST_OID,
1017               GenerateTOTPSharedSecretExtendedRequest.
1018                    GENERATE_TOTP_SHARED_SECRET_REQUEST_OID,
1019               GetConnectionIDExtendedRequest.GET_CONNECTION_ID_REQUEST_OID,
1020               GetPasswordQualityRequirementsExtendedRequest.
1021                    OID_GET_PASSWORD_QUALITY_REQUIREMENTS_REQUEST,
1022               PasswordPolicyStateExtendedRequest.
1023                    PASSWORD_POLICY_STATE_REQUEST_OID,
1024               RegisterYubiKeyOTPDeviceExtendedRequest.
1025                    REGISTER_YUBIKEY_OTP_DEVICE_REQUEST_OID,
1026               RevokeTOTPSharedSecretExtendedRequest.
1027                    REVOKE_TOTP_SHARED_SECRET_REQUEST_OID,
1028               StartAdministrativeSessionExtendedRequest.
1029                    START_ADMIN_SESSION_REQUEST_OID,
1030               ValidateTOTPPasswordExtendedRequest.
1031                    VALIDATE_TOTP_PASSWORD_REQUEST_OID))
1032        {
1033          if (! timeoutsByExtOpType.containsKey(oid))
1034          {
1035            timeoutsByExtOpType.put(oid, 30_000L);
1036          }
1037        }
1038      }
1039      else
1040      {
1041        timeoutsByOpType.put(OperationType.EXTENDED, extendedOpTimeout);
1042      }
1043    }
1044
1045    DEFAULT_RESPONSE_TIMEOUT_MILLIS = allOpsTimeout;
1046    DEFAULT_RESPONSE_TIMEOUT_MILLIS_BY_OPERATION_TYPE =
1047         Collections.unmodifiableMap(timeoutsByOpType);
1048    DEFAULT_RESPONSE_TIMEOUT_MILLIS_BY_EXTENDED_OPERATION_TYPE =
1049         Collections.unmodifiableMap(timeoutsByExtOpType);
1050  }
1051
1052
1053
1054  /**
1055   * The default value for the setting that controls the default behavior with
1056   * regard to whether to allow concurrent use of a socket factory to create
1057   * client connections.
1058   */
1059  private static final boolean DEFAULT_ALLOW_CONCURRENT_SOCKET_FACTORY_USE;
1060  static
1061  {
1062    final String vmVendor =
1063         StaticUtils.toLowerCase(System.getProperty("java.vm.vendor"));
1064    DEFAULT_ALLOW_CONCURRENT_SOCKET_FACTORY_USE = ((vmVendor != null) &&
1065         (vmVendor.contains("sun microsystems") ||
1066          vmVendor.contains("oracle") ||
1067          vmVendor.contains("apple") ||
1068          vmVendor.contains("azul systems")));
1069  }
1070
1071
1072
1073  /**
1074   * The default {@code SSLSocketVerifier} instance that will be used for
1075   * performing extra validation for {@code SSLSocket} instances.
1076   */
1077  private static final SSLSocketVerifier DEFAULT_SSL_SOCKET_VERIFIER =
1078       TrustAllSSLSocketVerifier.getInstance();
1079
1080
1081
1082  // Indicates whether to send an abandon request for any operation for which no
1083  // response is received in the maximum response timeout.
1084  private boolean abandonOnTimeout;
1085
1086  // Indicates whether to use synchronization prevent concurrent use of the
1087  // socket factory instance associated with a connection or set of connections.
1088  private boolean allowConcurrentSocketFactoryUse;
1089
1090  // Indicates whether the connection should attempt to automatically reconnect
1091  // if the connection to the server is lost.
1092  private boolean autoReconnect;
1093
1094  // Indicates whether to allow simple binds that contain a DN but no password.
1095  private boolean bindWithDNRequiresPassword;
1096
1097  // Indicates whether to capture a thread stack trace whenever an attempt is
1098  // made to establish a connection;
1099  private boolean captureConnectStackTrace;
1100
1101  // Indicates whether to attempt to follow any referrals that are encountered.
1102  private boolean followReferrals;
1103
1104  // Indicates whether to use SO_KEEPALIVE for the underlying sockets.
1105  private boolean useKeepAlive;
1106
1107  // Indicates whether to use SO_LINGER for the underlying sockets.
1108  private boolean useLinger;
1109
1110  // Indicates whether to use SO_REUSEADDR for the underlying sockets.
1111  private boolean useReuseAddress;
1112
1113  // Indicates whether all connections in a connection pool should reference
1114  // the same schema.
1115  private boolean usePooledSchema;
1116
1117  // Indicates whether to try to use schema information when reading data from
1118  // the server.
1119  private boolean useSchema;
1120
1121  // Indicates whether to use synchronous mode in which only a single operation
1122  // may be in progress on associated connections at any given time.
1123  private boolean useSynchronousMode;
1124
1125  // Indicates whether to use TCP_NODELAY for the underlying sockets.
1126  private boolean useTCPNoDelay;
1127
1128  // The disconnect handler for associated connections.
1129  private DisconnectHandler disconnectHandler;
1130
1131  // The connect timeout, in milliseconds.
1132  private int connectTimeoutMillis;
1133
1134  // The linger timeout to use if SO_LINGER is to be used.
1135  private int lingerTimeoutSeconds;
1136
1137  // The maximum message size in bytes that will be allowed when reading data
1138  // from a directory server.
1139  private int maxMessageSizeBytes;
1140
1141  // The socket receive buffer size to request.
1142  private int receiveBufferSizeBytes;
1143
1144  // The referral hop limit to use if referral following is enabled.
1145  private int referralHopLimit;
1146
1147  // The socket send buffer size to request.
1148  private int sendBufferSizeBytes;
1149
1150  // The pooled schema timeout, in milliseconds.
1151  private long pooledSchemaTimeoutMillis;
1152
1153  // The response timeout, in milliseconds.
1154  private long responseTimeoutMillis;
1155
1156  private Map<OperationType,Long> responseTimeoutMillisByOperationType;
1157
1158  private Map<String,Long> responseTimeoutMillisByExtendedOperationType;
1159
1160  // Tne default referral connector that should be used for associated
1161  // connections.
1162  private ReferralConnector referralConnector;
1163
1164  // The SSLSocketVerifier instance to use to perform extra validation on
1165  // newly-established SSLSocket instances.
1166  private SSLSocketVerifier sslSocketVerifier;
1167
1168  // The unsolicited notification handler for associated connections.
1169  private UnsolicitedNotificationHandler unsolicitedNotificationHandler;
1170
1171
1172
1173  /**
1174   * Creates a new set of LDAP connection options with the default settings.
1175   */
1176  public LDAPConnectionOptions()
1177  {
1178    abandonOnTimeout               = DEFAULT_ABANDON_ON_TIMEOUT;
1179    autoReconnect                  = DEFAULT_AUTO_RECONNECT;
1180    bindWithDNRequiresPassword     = DEFAULT_BIND_WITH_DN_REQUIRES_PASSWORD;
1181    captureConnectStackTrace       = DEFAULT_CAPTURE_CONNECT_STACK_TRACE;
1182    followReferrals                = DEFAULT_FOLLOW_REFERRALS;
1183    useKeepAlive                   = DEFAULT_USE_KEEPALIVE;
1184    useLinger                      = DEFAULT_USE_LINGER;
1185    useReuseAddress                = DEFAULT_USE_REUSE_ADDRESS;
1186    usePooledSchema                = DEFAULT_USE_POOLED_SCHEMA;
1187    useSchema                      = DEFAULT_USE_SCHEMA;
1188    useSynchronousMode             = DEFAULT_USE_SYNCHRONOUS_MODE;
1189    useTCPNoDelay                  = DEFAULT_USE_TCP_NODELAY;
1190    connectTimeoutMillis           = DEFAULT_CONNECT_TIMEOUT_MILLIS;
1191    lingerTimeoutSeconds           = DEFAULT_LINGER_TIMEOUT_SECONDS;
1192    maxMessageSizeBytes            = DEFAULT_MAX_MESSAGE_SIZE_BYTES;
1193    referralHopLimit               = DEFAULT_REFERRAL_HOP_LIMIT;
1194    pooledSchemaTimeoutMillis      = DEFAULT_POOLED_SCHEMA_TIMEOUT_MILLIS;
1195    responseTimeoutMillis          = DEFAULT_RESPONSE_TIMEOUT_MILLIS;
1196    receiveBufferSizeBytes         = DEFAULT_RECEIVE_BUFFER_SIZE_BYTES;
1197    sendBufferSizeBytes            = DEFAULT_SEND_BUFFER_SIZE_BYTES;
1198    disconnectHandler              = null;
1199    referralConnector              = null;
1200    sslSocketVerifier              = DEFAULT_SSL_SOCKET_VERIFIER;
1201    unsolicitedNotificationHandler = null;
1202
1203    responseTimeoutMillisByOperationType =
1204         DEFAULT_RESPONSE_TIMEOUT_MILLIS_BY_OPERATION_TYPE;
1205    responseTimeoutMillisByExtendedOperationType =
1206         DEFAULT_RESPONSE_TIMEOUT_MILLIS_BY_EXTENDED_OPERATION_TYPE;
1207    allowConcurrentSocketFactoryUse =
1208         DEFAULT_ALLOW_CONCURRENT_SOCKET_FACTORY_USE;
1209  }
1210
1211
1212
1213  /**
1214   * Returns a duplicate of this LDAP connection options object that may be
1215   * modified without impacting this instance.
1216   *
1217   * @return  A duplicate of this LDAP connection options object that may be
1218   *          modified without impacting this instance.
1219   */
1220  public LDAPConnectionOptions duplicate()
1221  {
1222    final LDAPConnectionOptions o = new LDAPConnectionOptions();
1223
1224    o.abandonOnTimeout                = abandonOnTimeout;
1225    o.allowConcurrentSocketFactoryUse = allowConcurrentSocketFactoryUse;
1226    o.autoReconnect                   = autoReconnect;
1227    o.bindWithDNRequiresPassword      = bindWithDNRequiresPassword;
1228    o.captureConnectStackTrace        = captureConnectStackTrace;
1229    o.followReferrals                 = followReferrals;
1230    o.useKeepAlive                    = useKeepAlive;
1231    o.useLinger                       = useLinger;
1232    o.useReuseAddress                 = useReuseAddress;
1233    o.usePooledSchema                 = usePooledSchema;
1234    o.useSchema                       = useSchema;
1235    o.useSynchronousMode              = useSynchronousMode;
1236    o.useTCPNoDelay                   = useTCPNoDelay;
1237    o.connectTimeoutMillis            = connectTimeoutMillis;
1238    o.lingerTimeoutSeconds            = lingerTimeoutSeconds;
1239    o.maxMessageSizeBytes             = maxMessageSizeBytes;
1240    o.pooledSchemaTimeoutMillis       = pooledSchemaTimeoutMillis;
1241    o.responseTimeoutMillis            = responseTimeoutMillis;
1242    o.referralConnector               = referralConnector;
1243    o.referralHopLimit                = referralHopLimit;
1244    o.disconnectHandler               = disconnectHandler;
1245    o.unsolicitedNotificationHandler  = unsolicitedNotificationHandler;
1246    o.receiveBufferSizeBytes          = receiveBufferSizeBytes;
1247    o.sendBufferSizeBytes             = sendBufferSizeBytes;
1248    o.sslSocketVerifier               = sslSocketVerifier;
1249
1250    o.responseTimeoutMillisByOperationType =
1251         responseTimeoutMillisByOperationType;
1252    o.responseTimeoutMillisByExtendedOperationType =
1253         responseTimeoutMillisByExtendedOperationType;
1254
1255    return o;
1256  }
1257
1258
1259
1260  /**
1261   * Indicates whether associated connections should attempt to automatically
1262   * reconnect to the target server if the connection is lost.  Note that this
1263   * option will not have any effect on pooled connections because defunct
1264   * pooled connections will be replaced by newly-created connections rather
1265   * than attempting to re-establish the existing connection.
1266   * <BR><BR>
1267   * NOTE:  The use of auto-reconnect is strongly discouraged because it is
1268   * inherently fragile and can only work under very limited circumstances.  It
1269   * is strongly recommended that a connection pool be used instead of the
1270   * auto-reconnect option, even in cases where only a single connection is
1271   * desired.
1272   *
1273   * @return  {@code true} if associated connections should attempt to
1274   *          automatically reconnect to the target server if the connection is
1275   *          lost, or {@code false} if not.
1276   *
1277   * @deprecated  The use of auto-reconnect is strongly discouraged because it
1278   *              is inherently fragile and can only work under very limited
1279   *              circumstances.  It is strongly recommended that a connection
1280   *              pool be used instead of the auto-reconnect option, even in
1281   *              cases where only a single connection is desired.
1282   */
1283  @Deprecated()
1284  public boolean autoReconnect()
1285  {
1286    return autoReconnect;
1287  }
1288
1289
1290
1291  /**
1292   * Specifies whether associated connections should attempt to automatically
1293   * reconnect to the target server if the connection is lost.  Note that
1294   * automatic reconnection will only be available for authenticated clients if
1295   * the authentication mechanism used provides support for re-binding on a new
1296   * connection.  Also note that this option will not have any effect on pooled
1297   * connections because defunct pooled connections will be replaced by
1298   * newly-created connections rather than attempting to re-establish the
1299   * existing connection.  Further, auto-reconnect should not be used with
1300   * connections that use StartTLS or some other mechanism to alter the state
1301   * of the connection beyond authentication.
1302   * <BR><BR>
1303   * NOTE:  The use of auto-reconnect is strongly discouraged because it is
1304   * inherently fragile and can only work under very limited circumstances.  It
1305   * is strongly recommended that a connection pool be used instead of the
1306   * auto-reconnect option, even in cases where only a single connection is
1307   * desired.
1308   *
1309   * @param  autoReconnect  Specifies whether associated connections should
1310   *                        attempt to automatically reconnect to the target
1311   *                        server if the connection is lost.
1312   *
1313   * @deprecated  The use of auto-reconnect is strongly discouraged because it
1314   *              is inherently fragile and can only work under very limited
1315   *              circumstances.  It is strongly recommended that a connection
1316   *              pool be used instead of the auto-reconnect option, even in
1317   *              cases where only a single connection is desired.
1318   */
1319  @Deprecated()
1320  public void setAutoReconnect(final boolean autoReconnect)
1321  {
1322    this.autoReconnect = autoReconnect;
1323  }
1324
1325
1326
1327  /**
1328   * Indicates whether the SDK should allow simple bind operations that contain
1329   * a bind DN but no password.  Binds of this type may represent a security
1330   * vulnerability in client applications because they may cause the client to
1331   * believe that the user is properly authenticated when the server considers
1332   * it to be an unauthenticated connection.
1333   *
1334   * @return  {@code true} if the SDK should allow simple bind operations that
1335   *          contain a bind DN but no password, or {@code false} if not.
1336   */
1337  public boolean bindWithDNRequiresPassword()
1338  {
1339    return bindWithDNRequiresPassword;
1340  }
1341
1342
1343
1344  /**
1345   * Specifies whether the SDK should allow simple bind operations that contain
1346   * a bind DN but no password.
1347   *
1348   * @param  bindWithDNRequiresPassword  Indicates whether the SDK should allow
1349   *                                     simple bind operations that contain a
1350   *                                     bind DN but no password.
1351   */
1352  public void setBindWithDNRequiresPassword(
1353                   final boolean bindWithDNRequiresPassword)
1354  {
1355    this.bindWithDNRequiresPassword = bindWithDNRequiresPassword;
1356  }
1357
1358
1359
1360  /**
1361   * Indicates whether the LDAP SDK should capture a thread stack trace for each
1362   * attempt made to establish a connection.  If this is enabled, then the
1363   * {@link LDAPConnection#getConnectStackTrace()}  method may be used to
1364   * retrieve the stack trace.
1365   *
1366   * @return  {@code true} if a thread stack trace should be captured whenever a
1367   *          connection is established, or {@code false} if not.
1368   */
1369  public boolean captureConnectStackTrace()
1370  {
1371    return captureConnectStackTrace;
1372  }
1373
1374
1375
1376  /**
1377   * Specifies whether the LDAP SDK should capture a thread stack trace for each
1378   * attempt made to establish a connection.
1379   *
1380   * @param  captureConnectStackTrace  Indicates whether to capture a thread
1381   *                                   stack trace for each attempt made to
1382   *                                   establish a connection.
1383   */
1384  public void setCaptureConnectStackTrace(
1385                   final boolean captureConnectStackTrace)
1386  {
1387    this.captureConnectStackTrace = captureConnectStackTrace;
1388  }
1389
1390
1391
1392  /**
1393   * Retrieves the maximum length of time in milliseconds that a connection
1394   * attempt should be allowed to continue before giving up.
1395   *
1396   * @return  The maximum length of time in milliseconds that a connection
1397   *          attempt should be allowed to continue before giving up, or zero
1398   *          to indicate that there should be no connect timeout.
1399   */
1400  public int getConnectTimeoutMillis()
1401  {
1402    return connectTimeoutMillis;
1403  }
1404
1405
1406
1407  /**
1408   * Specifies the maximum length of time in milliseconds that a connection
1409   * attempt should be allowed to continue before giving up.  A value of zero
1410   * indicates that there should be no connect timeout.
1411   *
1412   * @param  connectTimeoutMillis  The maximum length of time in milliseconds
1413   *                               that a connection attempt should be allowed
1414   *                               to continue before giving up.
1415   */
1416  public void setConnectTimeoutMillis(final int connectTimeoutMillis)
1417  {
1418    this.connectTimeoutMillis = connectTimeoutMillis;
1419  }
1420
1421
1422
1423  /**
1424   * Retrieves the maximum length of time in milliseconds that an operation
1425   * should be allowed to block while waiting for a response from the server.
1426   * This may be overridden on a per-operation type basis, so the
1427   * {@link #getResponseTimeoutMillis(OperationType)} method should be used
1428   * instead of this one.
1429   *
1430   * @return  The maximum length of time in milliseconds that an operation
1431   *          should be allowed to block while waiting for a response from the
1432   *          server, or zero if there should not be any default timeout.
1433   */
1434  public long getResponseTimeoutMillis()
1435  {
1436    return responseTimeoutMillis;
1437  }
1438
1439
1440
1441  /**
1442   * Specifies the maximum length of time in milliseconds that an operation
1443   * should be allowed to block while waiting for a response from the server.  A
1444   * value of zero indicates that there should be no timeout.  Note that this
1445   * will override any per-operation type and per-extended operation type
1446   * timeouts that had previously been set.
1447   *
1448   * @param  responseTimeoutMillis  The maximum length of time in milliseconds
1449   *                                that an operation should be allowed to block
1450   *                                while waiting for a response from the
1451   *                                server.
1452   */
1453  public void setResponseTimeoutMillis(final long responseTimeoutMillis)
1454  {
1455    this.responseTimeoutMillis = Math.max(0L, responseTimeoutMillis);
1456    responseTimeoutMillisByExtendedOperationType = Collections.emptyMap();
1457
1458    final EnumMap<OperationType,Long> newOperationTimeouts =
1459         new EnumMap<>(OperationType.class);
1460    for (final OperationType t : OperationType.values())
1461    {
1462      newOperationTimeouts.put(t, this.responseTimeoutMillis);
1463    }
1464    responseTimeoutMillisByOperationType =
1465         Collections.unmodifiableMap(newOperationTimeouts);
1466  }
1467
1468
1469
1470  /**
1471   * Retrieves the maximum length of time in milliseconds that an operation
1472   * of the specified type should be allowed to block while waiting for a
1473   * response from the server.  Note that for extended operations, the response
1474   * timeout may be overridden on a per-request OID basis, so the
1475   * {@link #getExtendedOperationResponseTimeoutMillis(String)} method should be
1476   * used instead of this one for extended operations.
1477   *
1478   * @param  operationType  The operation type for which to make the
1479   *                        determination.  It must not be {@code null}.
1480   *
1481   * @return  The maximum length of time in milliseconds that an operation of
1482   *          the specified type should be allowed to block while waiting for a
1483   *          response from the server, or zero if there should not be any
1484   *          default timeout.
1485   */
1486  public long getResponseTimeoutMillis(final OperationType operationType)
1487  {
1488    return responseTimeoutMillisByOperationType.get(operationType);
1489  }
1490
1491
1492
1493  /**
1494   * Specifies the maximum length of time in milliseconds that an operation of
1495   * the specified type should be allowed to block while waiting for a response
1496   * from the server.  A value of zero indicates that there should be no
1497   * timeout.
1498   *
1499   * @param  operationType          The operation type for which to set the
1500   *                                response timeout.  It must not be
1501   *                                {@code null}.
1502   * @param  responseTimeoutMillis  The maximum length of time in milliseconds
1503   *                                that an operation should be allowed to block
1504   *                                while waiting for a response from the
1505   *                                server.
1506   */
1507  public void setResponseTimeoutMillis(final OperationType operationType,
1508                                       final long responseTimeoutMillis)
1509  {
1510    final EnumMap<OperationType,Long> newOperationTimeouts =
1511         new EnumMap<>(OperationType.class);
1512    newOperationTimeouts.putAll(responseTimeoutMillisByOperationType);
1513    newOperationTimeouts.put(operationType,
1514         Math.max(0L, responseTimeoutMillis));
1515
1516    responseTimeoutMillisByOperationType = Collections.unmodifiableMap(
1517         newOperationTimeouts);
1518  }
1519
1520
1521
1522  /**
1523   * Retrieves the maximum length of time in milliseconds that an extended
1524   * operation with the specified request OID should be allowed to block while
1525   * waiting for a response from the server.
1526   *
1527   * @param  requestOID  The request OID for the extended operation for which to
1528   *                     make the determination.  It must not be {@code null}.
1529   *
1530   * @return  The maximum length of time in milliseconds that the specified type
1531   *          of extended operation should be allowed to block while waiting for
1532   *          a response from the server, or zero if there should not be any
1533   *          default timeout.
1534   */
1535  public long getExtendedOperationResponseTimeoutMillis(final String requestOID)
1536  {
1537    final Long timeout =
1538         responseTimeoutMillisByExtendedOperationType.get(requestOID);
1539    if (timeout == null)
1540    {
1541      return responseTimeoutMillisByOperationType.get(OperationType.EXTENDED);
1542    }
1543    else
1544    {
1545      return timeout;
1546    }
1547  }
1548
1549
1550
1551  /**
1552   * Specifies the maximum length of time in milliseconds that an extended
1553   * operation with the specified request OID should be allowed to block while
1554   * waiting for a response from the server.  A value of zero indicates that
1555   * there should be no timeout.
1556   *
1557   * @param  requestOID             The request OID for the extended operation
1558   *                                type for which to set the response timeout.
1559   *                                It must not be {@code null}.
1560   * @param  responseTimeoutMillis  The maximum length of time in milliseconds
1561   *                                that an operation should be allowed to block
1562   *                                while waiting for a response from the
1563   *                                server.
1564   */
1565  public void setExtendedOperationResponseTimeoutMillis(final String requestOID,
1566                   final long responseTimeoutMillis)
1567  {
1568    final HashMap<String,Long> newExtOpTimeouts =
1569         new HashMap<>(responseTimeoutMillisByExtendedOperationType);
1570    newExtOpTimeouts.put(requestOID, responseTimeoutMillis);
1571    responseTimeoutMillisByExtendedOperationType =
1572         Collections.unmodifiableMap(newExtOpTimeouts);
1573  }
1574
1575
1576
1577  /**
1578   * Indicates whether the LDAP SDK should attempt to abandon any request for
1579   * which no response is received in the maximum response timeout period.
1580   *
1581   * @return  {@code true} if the LDAP SDK should attempt to abandon any request
1582   *          for which no response is received in the maximum response timeout
1583   *          period, or {@code false} if no abandon attempt should be made in
1584   *          this circumstance.
1585   */
1586  public boolean abandonOnTimeout()
1587  {
1588    return abandonOnTimeout;
1589  }
1590
1591
1592
1593  /**
1594   * Specifies whether the LDAP SDK should attempt to abandon any request for
1595   * which no response is received in the maximum response timeout period.
1596   *
1597   * @param  abandonOnTimeout  Indicates whether the LDAP SDK should attempt to
1598   *                           abandon any request for which no response is
1599   *                           received in the maximum response timeout period.
1600   */
1601  public void setAbandonOnTimeout(final boolean abandonOnTimeout)
1602  {
1603    this.abandonOnTimeout = abandonOnTimeout;
1604  }
1605
1606
1607
1608  /**
1609   * Indicates whether to use the SO_KEEPALIVE option for the underlying sockets
1610   * used by associated connections.
1611   *
1612   * @return  {@code true} if the SO_KEEPALIVE option should be used for the
1613   *          underlying sockets, or {@code false} if not.
1614   */
1615  public boolean useKeepAlive()
1616  {
1617    return useKeepAlive;
1618  }
1619
1620
1621
1622  /**
1623   * Specifies whether to use the SO_KEEPALIVE option for the underlying sockets
1624   * used by associated connections.  Changes to this setting will take effect
1625   * only for new sockets, and not for existing sockets.
1626   *
1627   * @param  useKeepAlive  Indicates whether to use the SO_KEEPALIVE option for
1628   *                       the underlying sockets used by associated
1629   *                       connections.
1630   */
1631  public void setUseKeepAlive(final boolean useKeepAlive)
1632  {
1633    this.useKeepAlive = useKeepAlive;
1634  }
1635
1636
1637
1638  /**
1639   * Indicates whether to use the SO_LINGER option for the underlying sockets
1640   * used by associated connections.
1641   *
1642   * @return  {@code true} if the SO_LINGER option should be used for the
1643   *          underlying sockets, or {@code false} if not.
1644   */
1645  public boolean useLinger()
1646  {
1647    return useLinger;
1648  }
1649
1650
1651
1652  /**
1653   * Retrieves the linger timeout in seconds that will be used if the SO_LINGER
1654   * socket option is enabled.
1655   *
1656   * @return  The linger timeout in seconds that will be used if the SO_LINGER
1657   *          socket option is enabled.
1658   */
1659  public int getLingerTimeoutSeconds()
1660  {
1661    return lingerTimeoutSeconds;
1662  }
1663
1664
1665
1666  /**
1667   * Specifies whether to use the SO_LINGER option for the underlying sockets
1668   * used by associated connections.  Changes to this setting will take effect
1669   * only for new sockets, and not for existing sockets.
1670   *
1671   * @param  useLinger             Indicates whether to use the SO_LINGER option
1672   *                               for the underlying sockets used by associated
1673   *                               connections.
1674   * @param  lingerTimeoutSeconds  The linger timeout in seconds that should be
1675   *                               used if this capability is enabled.
1676   */
1677  public void setUseLinger(final boolean useLinger,
1678                           final int lingerTimeoutSeconds)
1679  {
1680    this.useLinger = useLinger;
1681    this.lingerTimeoutSeconds = lingerTimeoutSeconds;
1682  }
1683
1684
1685
1686  /**
1687   * Indicates whether to use the SO_REUSEADDR option for the underlying sockets
1688   * used by associated connections.
1689   *
1690   * @return  {@code true} if the SO_REUSEADDR option should be used for the
1691   *          underlying sockets, or {@code false} if not.
1692   */
1693  public boolean useReuseAddress()
1694  {
1695    return useReuseAddress;
1696  }
1697
1698
1699
1700  /**
1701   * Specifies whether to use the SO_REUSEADDR option for the underlying sockets
1702   * used by associated connections.  Changes to this setting will take effect
1703   * only for new sockets, and not for existing sockets.
1704   *
1705   * @param  useReuseAddress  Indicates whether to use the SO_REUSEADDR option
1706   *                          for the underlying sockets used by associated
1707   *                          connections.
1708   */
1709  public void setUseReuseAddress(final boolean useReuseAddress)
1710  {
1711    this.useReuseAddress = useReuseAddress;
1712  }
1713
1714
1715
1716  /**
1717   * Indicates whether to try to use schema information when reading data from
1718   * the server (e.g., to select the appropriate matching rules for the
1719   * attributes included in a search result entry).
1720   *
1721   * @return  {@code true} if schema should be used when reading data from the
1722   *          server, or {@code false} if not.
1723   */
1724  public boolean useSchema()
1725  {
1726    return useSchema;
1727  }
1728
1729
1730
1731  /**
1732   * Specifies whether to try to use schema information when reading data from
1733   * the server (e.g., to select the appropriate matching rules for the
1734   * attributes included in a search result entry).
1735   * <BR><BR>
1736   * Note that calling this method with a value of {@code true} will also cause
1737   * the {@code usePooledSchema} setting to be given a value of false, since
1738   * the two values should not both be {@code true} at the same time.
1739   *
1740   * @param  useSchema  Indicates whether to try to use schema information when
1741   *                    reading data from the server.
1742   */
1743  public void setUseSchema(final boolean useSchema)
1744  {
1745    this.useSchema = useSchema;
1746    if (useSchema)
1747    {
1748      usePooledSchema = false;
1749    }
1750  }
1751
1752
1753
1754  /**
1755   * Indicates whether to have connections that are part of a pool try to use
1756   * shared schema information when reading data from the server (e.g., to
1757   * select the appropriate matching rules for the attributes included in a
1758   * search result entry).  If this is {@code true}, then connections in a
1759   * connection pool will share the same cached schema information in a way that
1760   * attempts to reduce network bandwidth and connection establishment time (by
1761   * avoiding the need for each connection to retrieve its own copy of the
1762   * schema).
1763   * <BR><BR>
1764   * If pooled schema is to be used, then it may be configured to expire so that
1765   * the schema may be periodically re-retrieved for new connections to allow
1766   * schema updates to be incorporated.  This behavior is controlled by the
1767   * value returned by the {@link #getPooledSchemaTimeoutMillis} method.
1768   *
1769   * @return  {@code true} if all connections in a connection pool should
1770   *          reference the same schema object, or {@code false} if each
1771   *          connection should retrieve its own copy of the schema.
1772   */
1773  public boolean usePooledSchema()
1774  {
1775    return usePooledSchema;
1776  }
1777
1778
1779
1780  /**
1781   * Indicates whether to have connections that are part of a pool try to use
1782   * shared schema information when reading data from the server (e.g., to
1783   * select the appropriate matching rules for the attributes included in a
1784   * search result entry).
1785   * <BR><BR>
1786   * Note that calling this method with a value of {@code true} will also cause
1787   * the {@code useSchema} setting to be given a value of false, since the two
1788   * values should not both be {@code true} at the same time.
1789   *
1790   * @param  usePooledSchema  Indicates whether all connections in a connection
1791   *                          pool should reference the same schema object
1792   *                          rather than attempting to retrieve their own copy
1793   *                          of the schema.
1794   */
1795  public void setUsePooledSchema(final boolean usePooledSchema)
1796  {
1797    this.usePooledSchema = usePooledSchema;
1798    if (usePooledSchema)
1799    {
1800      useSchema = false;
1801    }
1802  }
1803
1804
1805
1806  /**
1807   * Retrieves the maximum length of time in milliseconds that a pooled schema
1808   * object should be considered fresh.  If the schema referenced by a
1809   * connection pool is at least this old, then the next connection attempt may
1810   * cause a new version of the schema to be retrieved.
1811   * <BR><BR>
1812   * This will only be used if the {@link #usePooledSchema} method returns
1813   * {@code true}.  A value of zero indicates that the pooled schema will never
1814   * expire.
1815   *
1816   * @return  The maximum length of time, in milliseconds, that a pooled schema
1817   *          object should be considered fresh, or zero if pooled schema
1818   *          objects should never expire.
1819   */
1820  public long getPooledSchemaTimeoutMillis()
1821  {
1822    return pooledSchemaTimeoutMillis;
1823  }
1824
1825
1826
1827  /**
1828   * Specifies the maximum length of time in milliseconds that a pooled schema
1829   * object should be considered fresh.
1830   *
1831   * @param  pooledSchemaTimeoutMillis  The maximum length of time in
1832   *                                    milliseconds that a pooled schema object
1833   *                                    should be considered fresh.  A value
1834   *                                    less than or equal to zero will indicate
1835   *                                    that pooled schema should never expire.
1836   */
1837  public void setPooledSchemaTimeoutMillis(final long pooledSchemaTimeoutMillis)
1838  {
1839    this.pooledSchemaTimeoutMillis = Math.max(0L, pooledSchemaTimeoutMillis);
1840  }
1841
1842
1843
1844  /**
1845   * Indicates whether to operate in synchronous mode, in which at most one
1846   * operation may be in progress at any time on a given connection, which may
1847   * allow it to operate more efficiently and without requiring a separate
1848   * reader thread per connection.  The LDAP SDK will not absolutely enforce
1849   * this restriction, but when operating in this mode correct behavior
1850   * cannot be guaranteed when multiple attempts are made to use a connection
1851   * for multiple concurrent operations.
1852   * <BR><BR>
1853   * Note that if synchronous mode is to be used, then this connection option
1854   * must be set on the connection before any attempt is made to establish the
1855   * connection.  Once the connection has been established, then it will
1856   * continue to operate in synchronous or asynchronous mode based on the
1857   * options in place at the time it was connected.
1858   *
1859   * @return  {@code true} if associated connections should operate in
1860   *          synchronous mode, or {@code false} if not.
1861   */
1862  public boolean useSynchronousMode()
1863  {
1864    return useSynchronousMode;
1865  }
1866
1867
1868
1869  /**
1870   * Specifies whether to operate in synchronous mode, in which at most one
1871   * operation may be in progress at any time on a given connection.
1872   * <BR><BR>
1873   * Note that if synchronous mode is to be used, then this connection option
1874   * must be set on the connection before any attempt is made to establish the
1875   * connection.  Once the connection has been established, then it will
1876   * continue to operate in synchronous or asynchronous mode based on the
1877   * options in place at the time it was connected.
1878   *
1879   * @param  useSynchronousMode  Indicates whether to operate in synchronous
1880   *                             mode.
1881   */
1882  public void setUseSynchronousMode(final boolean useSynchronousMode)
1883  {
1884    this.useSynchronousMode = useSynchronousMode;
1885  }
1886
1887
1888
1889  /**
1890   * Indicates whether to use the TCP_NODELAY option for the underlying sockets
1891   * used by associated connections.
1892   *
1893   * @return  {@code true} if the TCP_NODELAY option should be used for the
1894   *          underlying sockets, or {@code false} if not.
1895   */
1896  public boolean useTCPNoDelay()
1897  {
1898    return useTCPNoDelay;
1899  }
1900
1901
1902
1903  /**
1904   * Specifies whether to use the TCP_NODELAY option for the underlying sockets
1905   * used by associated connections.  Changes to this setting will take effect
1906   * only for new sockets, and not for existing sockets.
1907   *
1908   * @param  useTCPNoDelay  Indicates whether to use the TCP_NODELAY option for
1909   *                        the underlying sockets used by associated
1910   *                        connections.
1911   */
1912  public void setUseTCPNoDelay(final boolean useTCPNoDelay)
1913  {
1914    this.useTCPNoDelay = useTCPNoDelay;
1915  }
1916
1917
1918
1919  /**
1920   * Indicates whether associated connections should attempt to follow any
1921   * referrals that they encounter.
1922   *
1923   * @return  {@code true} if associated connections should attempt to follow
1924   *          any referrals that they encounter, or {@code false} if not.
1925   */
1926  public boolean followReferrals()
1927  {
1928    return followReferrals;
1929  }
1930
1931
1932
1933  /**
1934   * Specifies whether associated connections should attempt to follow any
1935   * referrals that they encounter, using the referral connector for the
1936   * associated connection.
1937   *
1938   * @param  followReferrals  Specifies whether associated connections should
1939   *                          attempt to follow any referrals that they
1940   *                          encounter.
1941   */
1942  public void setFollowReferrals(final boolean followReferrals)
1943  {
1944    this.followReferrals = followReferrals;
1945  }
1946
1947
1948
1949  /**
1950   * Retrieves the maximum number of hops that a connection should take when
1951   * trying to follow a referral.
1952   *
1953   * @return  The maximum number of hops that a connection should take when
1954   *          trying to follow a referral.
1955   */
1956  public int getReferralHopLimit()
1957  {
1958    return referralHopLimit;
1959  }
1960
1961
1962
1963  /**
1964   * Specifies the maximum number of hops that a connection should take when
1965   * trying to follow a referral.
1966   *
1967   * @param  referralHopLimit  The maximum number of hops that a connection
1968   *                           should take when trying to follow a referral.  It
1969   *                           must be greater than zero.
1970   */
1971  public void setReferralHopLimit(final int referralHopLimit)
1972  {
1973    ensureTrue(referralHopLimit > 0,
1974         "LDAPConnectionOptions.referralHopLimit must be greater than 0.");
1975
1976    this.referralHopLimit = referralHopLimit;
1977  }
1978
1979
1980
1981  /**
1982   * Retrieves the referral connector that will be used to establish and
1983   * optionally authenticate connections to servers when attempting to follow
1984   * referrals, if defined.
1985   *
1986   * @return  The referral connector that will be used to establish and
1987   *          optionally authenticate connections to servers when attempting to
1988   *          follow referrals, or {@code null} if no specific referral
1989   *          connector has been configured and referral connections should be
1990   *          created using the same socket factory and bind request as the
1991   *          connection on which the referral was received.
1992   */
1993  public ReferralConnector getReferralConnector()
1994  {
1995    return referralConnector;
1996  }
1997
1998
1999
2000  /**
2001   * Specifies the referral connector that should be used to establish and
2002   * optionally authenticate connections to servers when attempting to follow
2003   * referrals.
2004   *
2005   * @param  referralConnector  The referral connector that will be used to
2006   *                            establish and optionally authenticate
2007   *                            connections to servers when attempting to follow
2008   *                            referrals.  It may be {@code null} to indicate
2009   *                            that the same socket factory and bind request
2010   *                            as the connection on which the referral was
2011   *                            received should be used to establish and
2012   *                            authenticate connections for following
2013   *                            referrals.
2014   */
2015  public void setReferralConnector(final ReferralConnector referralConnector)
2016  {
2017    this.referralConnector = referralConnector;
2018  }
2019
2020
2021
2022  /**
2023   * Retrieves the maximum size in bytes for an LDAP message that a connection
2024   * will attempt to read from the directory server.  If it encounters an LDAP
2025   * message that is larger than this size, then the connection will be
2026   * terminated.
2027   *
2028   * @return  The maximum size in bytes for an LDAP message that a connection
2029   *          will attempt to read from the directory server, or 0 if no limit
2030   *          will be enforced.
2031   */
2032  public int getMaxMessageSize()
2033  {
2034    return maxMessageSizeBytes;
2035  }
2036
2037
2038
2039  /**
2040   * Specifies the maximum size in bytes for an LDAP message that a connection
2041   * will attempt to read from the directory server.  If it encounters an LDAP
2042   * message that is larger than this size, then the connection will be
2043   * terminated.
2044   *
2045   * @param  maxMessageSizeBytes  The maximum size in bytes for an LDAP message
2046   *                              that a connection will attempt to read from
2047   *                              the directory server.  A value less than or
2048   *                              equal to zero indicates that no limit should
2049   *                              be enforced.
2050   */
2051  public void setMaxMessageSize(final int maxMessageSizeBytes)
2052  {
2053    this.maxMessageSizeBytes = Math.max(0, maxMessageSizeBytes);
2054  }
2055
2056
2057
2058  /**
2059   * Retrieves the disconnect handler to use for associated connections.
2060   *
2061   * @return  the disconnect handler to use for associated connections, or
2062   *          {@code null} if none is defined.
2063   */
2064  public DisconnectHandler getDisconnectHandler()
2065  {
2066    return disconnectHandler;
2067  }
2068
2069
2070
2071  /**
2072   * Specifies the disconnect handler to use for associated connections.
2073   *
2074   * @param  handler  The disconnect handler to use for associated connections.
2075   */
2076  public void setDisconnectHandler(final DisconnectHandler handler)
2077  {
2078    disconnectHandler = handler;
2079  }
2080
2081
2082
2083  /**
2084   * Retrieves the unsolicited notification handler to use for associated
2085   * connections.
2086   *
2087   * @return  The unsolicited notification handler to use for associated
2088   *          connections, or {@code null} if none is defined.
2089   */
2090  public UnsolicitedNotificationHandler getUnsolicitedNotificationHandler()
2091  {
2092    return unsolicitedNotificationHandler;
2093  }
2094
2095
2096
2097  /**
2098   * Specifies the unsolicited notification handler to use for associated
2099   * connections.
2100   *
2101   * @param  handler  The unsolicited notification handler to use for associated
2102   *                  connections.
2103   */
2104  public void setUnsolicitedNotificationHandler(
2105                   final UnsolicitedNotificationHandler handler)
2106  {
2107    unsolicitedNotificationHandler = handler;
2108  }
2109
2110
2111
2112  /**
2113   * Retrieves the socket receive buffer size, in bytes, that should be
2114   * requested when establishing a connection.
2115   *
2116   * @return  The socket receive buffer size, in bytes, that should be requested
2117   *          when establishing a connection, or zero if the JVM's default size
2118   *          should be used.
2119   */
2120  public int getReceiveBufferSize()
2121  {
2122    return receiveBufferSizeBytes;
2123  }
2124
2125
2126
2127  /**
2128   * Specifies the socket receive buffer size, in bytes, that should be
2129   * requested when establishing a connection.
2130   *
2131   * @param  receiveBufferSizeBytes  The socket receive buffer size, in bytes,
2132   *                                 that should be requested when establishing
2133   *                                 a connection, or zero if the JVM's default
2134   *                                 size should be used.
2135   */
2136  public void setReceiveBufferSize(final int receiveBufferSizeBytes)
2137  {
2138    this.receiveBufferSizeBytes = Math.max(0, receiveBufferSizeBytes);
2139  }
2140
2141
2142
2143  /**
2144   * Retrieves the socket send buffer size, in bytes, that should be requested
2145   * when establishing a connection.
2146   *
2147   * @return  The socket send buffer size, in bytes, that should be requested
2148   *          when establishing a connection, or zero if the JVM's default size
2149   *          should be used.
2150   */
2151  public int getSendBufferSize()
2152  {
2153    return sendBufferSizeBytes;
2154  }
2155
2156
2157
2158  /**
2159   * Specifies the socket send buffer size, in bytes, that should be requested
2160   * when establishing a connection.
2161   *
2162   * @param  sendBufferSizeBytes  The socket send buffer size, in bytes, that
2163   *                              should be requested when establishing a
2164   *                              connection, or zero if the JVM's default size
2165   *                              should be used.
2166   */
2167  public void setSendBufferSize(final int sendBufferSizeBytes)
2168  {
2169    this.sendBufferSizeBytes = Math.max(0, sendBufferSizeBytes);
2170  }
2171
2172
2173
2174  /**
2175   * Indicates whether to allow a socket factory instance (which may be shared
2176   * across multiple connections) to be used create multiple sockets
2177   * concurrently.  In general, socket factory implementations are threadsafe
2178   * and can be to create multiple connections simultaneously across separate
2179   * threads, but this is known to not be the case in some VM implementations
2180   * (e.g., SSL socket factories in IBM JVMs).  This setting may be used to
2181   * indicate whether concurrent socket creation attempts should be allowed
2182   * (which may allow for better and more consistent performance, especially in
2183   * cases where a connection attempt fails due to a timeout) or prevented
2184   * (which may be necessary for non-threadsafe socket factory implementations).
2185   *
2186   * @return  {@code true} if multiple threads should be able to concurrently
2187   *          use the same socket factory instance, or {@code false} if Java
2188   *          synchronization should be used to ensure that no more than one
2189   *          thread is allowed to use a socket factory at any given time.
2190   */
2191  public boolean allowConcurrentSocketFactoryUse()
2192  {
2193    return allowConcurrentSocketFactoryUse;
2194  }
2195
2196
2197
2198  /**
2199   * Specifies whether to allow a socket factory instance (which may be shared
2200   * across multiple connections) to be used create multiple sockets
2201   * concurrently.  In general, socket factory implementations are threadsafe
2202   * and can be to create multiple connections simultaneously across separate
2203   * threads, but this is known to not be the case in some VM implementations
2204   * (e.g., SSL socket factories in IBM JVMs).  This setting may be used to
2205   * indicate whether concurrent socket creation attempts should be allowed
2206   * (which may allow for better and more consistent performance, especially in
2207   * cases where a connection attempt fails due to a timeout) or prevented
2208   * (which may be necessary for non-threadsafe socket factory implementations).
2209   *
2210   * @param  allowConcurrentSocketFactoryUse  Indicates whether to allow a
2211   *                                          socket factory instance to be used
2212   *                                          to create multiple sockets
2213   *                                          concurrently.
2214   */
2215  public void setAllowConcurrentSocketFactoryUse(
2216                   final boolean allowConcurrentSocketFactoryUse)
2217  {
2218    this.allowConcurrentSocketFactoryUse = allowConcurrentSocketFactoryUse;
2219  }
2220
2221
2222
2223  /**
2224   * Retrieves the {@link SSLSocketVerifier} that will be used to perform
2225   * additional validation for any newly-created {@code SSLSocket} instances.
2226   *
2227   * @return  The {@code SSLSocketVerifier} that will be used to perform
2228   *          additional validation for any newly-created {@code SSLSocket}
2229   *          instances.
2230   */
2231  public SSLSocketVerifier getSSLSocketVerifier()
2232  {
2233    return sslSocketVerifier;
2234  }
2235
2236
2237
2238  /**
2239   * Specifies the {@link SSLSocketVerifier} that will be used to perform
2240   * additional validation for any newly-created {@code SSLSocket} instances.
2241   *
2242   * @param  sslSocketVerifier  The {@code SSLSocketVerifier} that will be used
2243   *                            to perform additional validation for any
2244   *                            newly-created {@code SSLSocket} instances.
2245   */
2246  public void setSSLSocketVerifier(final SSLSocketVerifier sslSocketVerifier)
2247  {
2248    if (sslSocketVerifier == null)
2249    {
2250      this.sslSocketVerifier = DEFAULT_SSL_SOCKET_VERIFIER;
2251    }
2252    else
2253    {
2254      this.sslSocketVerifier = sslSocketVerifier;
2255    }
2256  }
2257
2258
2259
2260  /**
2261   * Retrieves the value of the specified system property as a boolean.
2262   *
2263   * @param  propertyName  The name of the system property whose value should be
2264   *                       retrieved.
2265   * @param  defaultValue  The default value that will be returned if the system
2266   *                       property is not defined or if its value cannot be
2267   *                       parsed as a boolean.
2268   *
2269   * @return  The value of the specified system property as an boolean, or the
2270   *          default value if the system property is not set with a valid
2271   *          value.
2272   */
2273  static boolean getSystemProperty(final String propertyName,
2274                                   final boolean defaultValue)
2275  {
2276    final String propertyValue = System.getProperty(propertyName);
2277    if (propertyValue == null)
2278    {
2279      if (Debug.debugEnabled())
2280      {
2281        Debug.debug(Level.FINE, DebugType.OTHER,
2282             "Using the default value of " + defaultValue + " for system " +
2283                  "property '" + propertyName + "' that is not set.");
2284      }
2285
2286      return defaultValue;
2287    }
2288
2289    if (propertyValue.equalsIgnoreCase("true"))
2290    {
2291      if (Debug.debugEnabled())
2292      {
2293        Debug.debug(Level.INFO, DebugType.OTHER,
2294             "Using value '" + propertyValue + "' set for system property '" +
2295                  propertyName + "'.");
2296      }
2297
2298      return true;
2299    }
2300    else if (propertyValue.equalsIgnoreCase("false"))
2301    {
2302      if (Debug.debugEnabled())
2303      {
2304        Debug.debug(Level.INFO, DebugType.OTHER,
2305             "Using value '" + propertyValue + "' set for system property '" +
2306                  propertyName + "'.");
2307      }
2308
2309      return false;
2310    }
2311    else
2312    {
2313      if (Debug.debugEnabled())
2314      {
2315        Debug.debug(Level.WARNING, DebugType.OTHER,
2316             "Invalid value '" + propertyValue + "' set for system property '" +
2317                  propertyName + "'.  The value was expected to be either " +
2318                  "'true' or 'false'.  The default value of " + defaultValue +
2319                  " will be used instead of the configured value.");
2320      }
2321
2322      return defaultValue;
2323    }
2324  }
2325
2326
2327
2328  /**
2329   * Retrieves the value of the specified system property as an integer.
2330   *
2331   * @param  propertyName  The name of the system property whose value should be
2332   *                       retrieved.
2333   * @param  defaultValue  The default value that will be returned if the system
2334   *                       property is not defined or if its value cannot be
2335   *                       parsed as an integer.
2336   *
2337   * @return  The value of the specified system property as an integer, or the
2338   *          default value if the system property is not set with a valid
2339   *          value.
2340   */
2341  static int getSystemProperty(final String propertyName,
2342                               final int defaultValue)
2343  {
2344    final String propertyValueString = System.getProperty(propertyName);
2345    if (propertyValueString == null)
2346    {
2347      if (Debug.debugEnabled())
2348      {
2349        Debug.debug(Level.FINE, DebugType.OTHER,
2350             "Using the default value of " + defaultValue + " for system " +
2351                  "property '" + propertyName + "' that is not set.");
2352      }
2353
2354      return defaultValue;
2355    }
2356
2357    try
2358    {
2359      final int propertyValueInt = Integer.parseInt(propertyValueString);
2360      if (Debug.debugEnabled())
2361      {
2362        Debug.debug(Level.INFO, DebugType.OTHER,
2363             "Using value " + propertyValueInt + " set for system property '" +
2364                  propertyName + "'.");
2365      }
2366
2367      return propertyValueInt;
2368    }
2369    catch (final Exception e)
2370    {
2371      if (Debug.debugEnabled())
2372      {
2373        Debug.debugException(e);
2374        Debug.debug(Level.WARNING, DebugType.OTHER,
2375             "Invalid value '" + propertyValueString + "' set for system " +
2376                  "property '" + propertyName + "'.  The value was expected " +
2377                  "to be an integer.  The default value of " + defaultValue +
2378                  "will be used instead of the configured value.",
2379             e);
2380      }
2381
2382      return defaultValue;
2383    }
2384  }
2385
2386
2387
2388  /**
2389   * Retrieves the value of the specified system property as a long.
2390   *
2391   * @param  propertyName  The name of the system property whose value should be
2392   *                       retrieved.
2393   * @param  defaultValue  The default value that will be returned if the system
2394   *                       property is not defined or if its value cannot be
2395   *                       parsed as a long.
2396   *
2397   * @return  The value of the specified system property as a long, or the
2398   *          default value if the system property is not set with a valid
2399   *          value.
2400   */
2401  static Long getSystemProperty(final String propertyName,
2402                                final Long defaultValue)
2403  {
2404    final String propertyValueString = System.getProperty(propertyName);
2405    if (propertyValueString == null)
2406    {
2407      if (Debug.debugEnabled())
2408      {
2409        Debug.debug(Level.FINE, DebugType.OTHER,
2410             "Using the default value of " + defaultValue + " for system " +
2411                  "property '" + propertyName + "' that is not set.");
2412      }
2413
2414      return defaultValue;
2415    }
2416
2417    try
2418    {
2419      final long propertyValueLong = Long.parseLong(propertyValueString);
2420      if (Debug.debugEnabled())
2421      {
2422        Debug.debug(Level.INFO, DebugType.OTHER,
2423             "Using value " + propertyValueLong + " set for system property '" +
2424                  propertyName + "'.");
2425      }
2426
2427      return propertyValueLong;
2428    }
2429    catch (final Exception e)
2430    {
2431      if (Debug.debugEnabled())
2432      {
2433        Debug.debugException(e);
2434        Debug.debug(Level.WARNING, DebugType.OTHER,
2435             "Invalid value '" + propertyValueString + "' set for system " +
2436                  "property '" + propertyName + "'.  The value was expected " +
2437                  "to be a long.  The default value of " + defaultValue +
2438                  "will be used instead of the configured value.",
2439             e);
2440      }
2441
2442      return defaultValue;
2443    }
2444  }
2445
2446
2447
2448  /**
2449   * Retrieves a string representation of this LDAP connection.
2450   *
2451   * @return  A string representation of this LDAP connection.
2452   */
2453  @Override()
2454  public String toString()
2455  {
2456    final StringBuilder buffer = new StringBuilder();
2457    toString(buffer);
2458    return buffer.toString();
2459  }
2460
2461
2462
2463  /**
2464   * Appends a string representation of this LDAP connection to the provided
2465   * buffer.
2466   *
2467   * @param  buffer  The buffer to which to append a string representation of
2468   *                 this LDAP connection.
2469   */
2470  public void toString(final StringBuilder buffer)
2471  {
2472    buffer.append("LDAPConnectionOptions(autoReconnect=");
2473    buffer.append(autoReconnect);
2474    buffer.append(", bindWithDNRequiresPassword=");
2475    buffer.append(bindWithDNRequiresPassword);
2476    buffer.append(", followReferrals=");
2477    buffer.append(followReferrals);
2478    if (followReferrals)
2479    {
2480      buffer.append(", referralHopLimit=");
2481      buffer.append(referralHopLimit);
2482    }
2483    if (referralConnector != null)
2484    {
2485      buffer.append(", referralConnectorClass=");
2486      buffer.append(referralConnector.getClass().getName());
2487    }
2488    buffer.append(", useKeepAlive=");
2489    buffer.append(useKeepAlive);
2490    buffer.append(", useLinger=");
2491    if (useLinger)
2492    {
2493      buffer.append("true, lingerTimeoutSeconds=");
2494      buffer.append(lingerTimeoutSeconds);
2495    }
2496    else
2497    {
2498      buffer.append("false");
2499    }
2500    buffer.append(", useReuseAddress=");
2501    buffer.append(useReuseAddress);
2502    buffer.append(", useSchema=");
2503    buffer.append(useSchema);
2504    buffer.append(", usePooledSchema=");
2505    buffer.append(usePooledSchema);
2506    buffer.append(", pooledSchemaTimeoutMillis=");
2507    buffer.append(pooledSchemaTimeoutMillis);
2508    buffer.append(", useSynchronousMode=");
2509    buffer.append(useSynchronousMode);
2510    buffer.append(", useTCPNoDelay=");
2511    buffer.append(useTCPNoDelay);
2512    buffer.append(", captureConnectStackTrace=");
2513    buffer.append(captureConnectStackTrace);
2514    buffer.append(", connectTimeoutMillis=");
2515    buffer.append(connectTimeoutMillis);
2516    buffer.append(", responseTimeoutMillis=");
2517    buffer.append(responseTimeoutMillis);
2518
2519    for (final Map.Entry<OperationType,Long> e :
2520         responseTimeoutMillisByOperationType.entrySet())
2521    {
2522      buffer.append(", responseTimeoutMillis.");
2523      buffer.append(e.getKey().name());
2524      buffer.append('=');
2525      buffer.append(e.getValue());
2526    }
2527
2528    for (final Map.Entry<String,Long> e :
2529         responseTimeoutMillisByExtendedOperationType.entrySet())
2530    {
2531      buffer.append(", responseTimeoutMillis.EXTENDED.");
2532      buffer.append(e.getKey());
2533      buffer.append('=');
2534      buffer.append(e.getValue());
2535    }
2536
2537    buffer.append(", abandonOnTimeout=");
2538    buffer.append(abandonOnTimeout);
2539    buffer.append(", maxMessageSizeBytes=");
2540    buffer.append(maxMessageSizeBytes);
2541    buffer.append(", receiveBufferSizeBytes=");
2542    buffer.append(receiveBufferSizeBytes);
2543    buffer.append(", sendBufferSizeBytes=");
2544    buffer.append(sendBufferSizeBytes);
2545    buffer.append(", allowConcurrentSocketFactoryUse=");
2546    buffer.append(allowConcurrentSocketFactoryUse);
2547    if (disconnectHandler != null)
2548    {
2549      buffer.append(", disconnectHandlerClass=");
2550      buffer.append(disconnectHandler.getClass().getName());
2551    }
2552    if (unsolicitedNotificationHandler != null)
2553    {
2554      buffer.append(", unsolicitedNotificationHandlerClass=");
2555      buffer.append(unsolicitedNotificationHandler.getClass().getName());
2556    }
2557
2558    buffer.append(", sslSocketVerifierClass='");
2559    buffer.append(sslSocketVerifier.getClass().getName());
2560    buffer.append('\'');
2561
2562    buffer.append(')');
2563  }
2564}