Class LDAPConnectionOptions


  • @Mutable
    @ThreadSafety(level=NOT_THREADSAFE)
    public final class LDAPConnectionOptions
    extends java.lang.Object
    This class provides a data structure that may be used to configure a number of connection-related properties. Elements included in the set of connection options include:
    • A flag that indicates whether the SDK should attempt to automatically re-establish a connection if it is unexpectedly closed. By default, it will not attempt to do so.
    • A flag that indicates whether simple bind attempts that contain a non-empty DN will be required to have a non-empty password. By default, a password will be required in such cases.
    • A flag that indicates whether to automatically attempt to follow any referrals that may be returned by the server. By default, it will not automatically attempt to follow referrals.
    • A referral hop limit, which indicates the maximum number of hops that the connection may take when trying to follow a referral. The default referral hop limit is five.
    • The referral connector that should be used to create and optionally authenticate connections used to follow referrals encountered during processing. By default, referral connections will use the same socket factory and bind request as the client connection on which the referral was received.
    • A flag that indicates whether to use the SO_KEEPALIVE socket option to attempt to more quickly detect when idle TCP connections have been lost or to prevent them from being unexpectedly closed by intermediate network hardware. By default, the SO_KEEPALIVE socket option will be used.
    • A flag that indicates whether to use the SO_LINGER socket option to indicate how long a connection should linger after it has been closed, and a value that specifies the length of time that it should linger. By default, the SO_LINGER option will be used with a timeout of 5 seconds.
    • A flag that indicates whether to use the SO_REUSEADDR socket option to indicate that a socket in a TIME_WAIT state may be reused. By default, the SO_REUSEADDR socket option will be used.
    • A flag that indicates whether to operate in synchronous mode, in which connections may exhibit better performance and will not require a separate reader thread, but will not allow multiple concurrent operations to be used on the same connection.
    • A flag that indicates whether to use the TCP_NODELAY socket option to indicate that any data written to the socket will be sent immediately rather than delaying for a short amount of time to see if any more data is to be sent that could potentially be included in the same packet. By default, the TCP_NODELAY socket option will be used.
    • A value that specifies the maximum length of time in milliseconds that an attempt to establish a connection should be allowed to block before failing. By default, a timeout of 10,000 milliseconds (10 seconds) will be used.
    • A value that specifies the default timeout in milliseconds that the SDK should wait for a response from the server before failing. This can be defined on a per-operation-type basis, with a default of 300,000 milliseconds (5 minutes) for search and extended operations, and a default timeout of 30,000 milliseconds (30 seconds) for all other types of operations. Further, the extended operation timeout can be customized on a per-operation-type basis, and a number of extended operation types have been configured with a 30,000 millisecond timeout by default. Individual requests can also be configured with their own response timeouts, and if provided, that timeout will override the default timeout from the connection options.
    • A flag that indicates whether to attempt to abandon any request for which no response is received after waiting for the maximum response timeout. By default, no abandon request will be sent.
    • A value which specifies the largest LDAP message size that the SDK will be willing to read from the directory server. By default, the SDK will not allow responses larger than 20,971,520 bytes (20MB). If it encounters a message that may be larger than the maximum allowed message size, then the SDK will terminate the connection to the server.
    • The LDAPConnectionLogger that should be used to record information about requests sent and responses received over connections with this set of options. By default, no LDAPConnectionLogger will be used.
    • The DisconnectHandler that should be used to receive notification if connection is disconnected for any reason. By default, no DisconnectHandler will be used.
    • The UnsolicitedNotificationHandler that should be used to receive notification about any unsolicited notifications returned by the server. By default, no UnsolicitedNotificationHandler will be used.
    • A flag that indicates whether to capture a thread stack trace whenever a new connection is established. Capturing a thread stack trace when establishing a connection may be marginally expensive, but can be useful for debugging certain kinds of problems like leaked connections (connections that are established but never explicitly closed). By default, connect stack traces will not be captured.
    • A flag that indicates whether connections should try to retrieve schema information from the server, which may be used to better determine which matching rules should be used when comparing attribute values. By default, server schema information will not be retrieved.
    • The size of the socket receive buffer, which may be used for temporarily holding data received from the directory server until it can be read and processed by the LDAP SDK. By default, the receive buffer size will be automatically determined by the JVM based on the underlying system settings.
    • The size of the socket send buffer, which may be used for temporarily holding data to be sent to the directory server until it can actually be transmitted over the network. By default, the send buffer size will be automatically determined by the JVM based on the underlying system settings.
    • A flag which indicates whether to allow a single socket factory instance (which may be shared across multiple connections) to be used to create multiple concurrent connections. This offers better and more predictable performance on some JVM implementations (especially when connection attempts fail as a result of a connection timeout), but some JVMs are known to use non-threadsafe socket factory implementations and may fail from concurrent use (for example, at least some IBM JVMs exhibit this behavior). By default, Sun/Oracle JVMs will allow concurrent socket factory use, but JVMs from other vendors will use synchronization to ensure that a socket factory will only be allowed to create one connection at a time.
    • A class that may be used to perform additional verification (e.g., hostname validation) for any SSLSocket instances created. By default, no special verification will be performed.
    • Constructor Summary

      Constructors 
      Constructor Description
      LDAPConnectionOptions()
      Creates a new set of LDAP connection options with the default settings.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      boolean abandonOnTimeout()
      Indicates whether the LDAP SDK should attempt to abandon any request for which no response is received in the maximum response timeout period.
      boolean allowConcurrentSocketFactoryUse()
      Indicates whether to allow a socket factory instance (which may be shared across multiple connections) to be used create multiple sockets concurrently.
      boolean autoReconnect()
      Deprecated.
      The use of auto-reconnect is strongly discouraged because it is inherently fragile and can only work under very limited circumstances.
      boolean bindWithDNRequiresPassword()
      Indicates whether the SDK should allow simple bind operations that contain a bind DN but no password.
      boolean captureConnectStackTrace()
      Indicates whether the LDAP SDK should capture a thread stack trace for each attempt made to establish a connection.
      LDAPConnectionOptions duplicate()
      Returns a duplicate of this LDAP connection options object that may be modified without impacting this instance.
      boolean followReferrals()
      Indicates whether associated connections should attempt to follow any referrals that they encounter.
      LDAPConnectionLogger getConnectionLogger()
      Retrieves the logger that should be used to record information about requests sent and responses received over connections with this set of connection options.
      int getConnectTimeoutMillis()
      Retrieves the maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up.
      DisconnectHandler getDisconnectHandler()
      Retrieves the disconnect handler to use for associated connections.
      long getExtendedOperationResponseTimeoutMillis​(java.lang.String requestOID)
      Retrieves the maximum length of time in milliseconds that an extended operation with the specified request OID should be allowed to block while waiting for a response from the server.
      int getLingerTimeoutSeconds()
      Retrieves the linger timeout in seconds that will be used if the SO_LINGER socket option is enabled.
      int getMaxMessageSize()
      Retrieves the maximum size in bytes for an LDAP message that a connection will attempt to read from the directory server.
      NameResolver getNameResolver()
      Retrieves the name resolver that should be used to resolve host names to IP addresses.
      long getPooledSchemaTimeoutMillis()
      Retrieves the maximum length of time in milliseconds that a pooled schema object should be considered fresh.
      int getReceiveBufferSize()
      Retrieves the socket receive buffer size, in bytes, that should be requested when establishing a connection.
      ReferralConnector getReferralConnector()
      Retrieves the referral connector that will be used to establish and optionally authenticate connections to servers when attempting to follow referrals, if defined.
      int getReferralHopLimit()
      Retrieves the maximum number of hops that a connection should take when trying to follow a referral.
      long getResponseTimeoutMillis()
      Retrieves the maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server.
      long getResponseTimeoutMillis​(OperationType operationType)
      Retrieves the maximum length of time in milliseconds that an operation of the specified type should be allowed to block while waiting for a response from the server.
      int getSendBufferSize()
      Retrieves the socket send buffer size, in bytes, that should be requested when establishing a connection.
      SSLSocketVerifier getSSLSocketVerifier()
      Retrieves the SSLSocketVerifier that will be used to perform additional validation for any newly-created SSLSocket instances.
      UnsolicitedNotificationHandler getUnsolicitedNotificationHandler()
      Retrieves the unsolicited notification handler to use for associated connections.
      void setAbandonOnTimeout​(boolean abandonOnTimeout)
      Specifies whether the LDAP SDK should attempt to abandon any request for which no response is received in the maximum response timeout period.
      void setAllowConcurrentSocketFactoryUse​(boolean allowConcurrentSocketFactoryUse)
      Specifies whether to allow a socket factory instance (which may be shared across multiple connections) to be used create multiple sockets concurrently.
      void setAutoReconnect​(boolean autoReconnect)
      Deprecated.
      The use of auto-reconnect is strongly discouraged because it is inherently fragile and can only work under very limited circumstances.
      void setBindWithDNRequiresPassword​(boolean bindWithDNRequiresPassword)
      Specifies whether the SDK should allow simple bind operations that contain a bind DN but no password.
      void setCaptureConnectStackTrace​(boolean captureConnectStackTrace)
      Specifies whether the LDAP SDK should capture a thread stack trace for each attempt made to establish a connection.
      void setConnectionLogger​(LDAPConnectionLogger connectionLogger)
      Specifies the logger that should be used to record information about requests sent and responses received over connections with this set of connection options.
      void setConnectTimeoutMillis​(int connectTimeoutMillis)
      Specifies the maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up.
      void setDisconnectHandler​(DisconnectHandler handler)
      Specifies the disconnect handler to use for associated connections.
      void setExtendedOperationResponseTimeoutMillis​(java.lang.String requestOID, long responseTimeoutMillis)
      Specifies the maximum length of time in milliseconds that an extended operation with the specified request OID should be allowed to block while waiting for a response from the server.
      void setFollowReferrals​(boolean followReferrals)
      Specifies whether associated connections should attempt to follow any referrals that they encounter, using the referral connector for the associated connection.
      void setMaxMessageSize​(int maxMessageSizeBytes)
      Specifies the maximum size in bytes for an LDAP message that a connection will attempt to read from the directory server.
      void setNameResolver​(NameResolver nameResolver)
      Sets the name resolver that should be used to resolve host names to IP addresses.
      void setPooledSchemaTimeoutMillis​(long pooledSchemaTimeoutMillis)
      Specifies the maximum length of time in milliseconds that a pooled schema object should be considered fresh.
      void setReceiveBufferSize​(int receiveBufferSizeBytes)
      Specifies the socket receive buffer size, in bytes, that should be requested when establishing a connection.
      void setReferralConnector​(ReferralConnector referralConnector)
      Specifies the referral connector that should be used to establish and optionally authenticate connections to servers when attempting to follow referrals.
      void setReferralHopLimit​(int referralHopLimit)
      Specifies the maximum number of hops that a connection should take when trying to follow a referral.
      void setResponseTimeoutMillis​(long responseTimeoutMillis)
      Specifies the maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server.
      void setResponseTimeoutMillis​(OperationType operationType, long responseTimeoutMillis)
      Specifies the maximum length of time in milliseconds that an operation of the specified type should be allowed to block while waiting for a response from the server.
      void setSendBufferSize​(int sendBufferSizeBytes)
      Specifies the socket send buffer size, in bytes, that should be requested when establishing a connection.
      void setSSLSocketVerifier​(SSLSocketVerifier sslSocketVerifier)
      Specifies the SSLSocketVerifier that will be used to perform additional validation for any newly-created SSLSocket instances.
      void setUnsolicitedNotificationHandler​(UnsolicitedNotificationHandler handler)
      Specifies the unsolicited notification handler to use for associated connections.
      void setUseKeepAlive​(boolean useKeepAlive)
      Specifies whether to use the SO_KEEPALIVE option for the underlying sockets used by associated connections.
      void setUseLinger​(boolean useLinger, int lingerTimeoutSeconds)
      Specifies whether to use the SO_LINGER option for the underlying sockets used by associated connections.
      void setUsePooledSchema​(boolean usePooledSchema)
      Indicates whether to have connections that are part of a pool try to use shared schema information when reading data from the server (e.g., to select the appropriate matching rules for the attributes included in a search result entry).
      void setUseReuseAddress​(boolean useReuseAddress)
      Specifies whether to use the SO_REUSEADDR option for the underlying sockets used by associated connections.
      void setUseSchema​(boolean useSchema)
      Specifies whether to try to use schema information when reading data from the server (e.g., to select the appropriate matching rules for the attributes included in a search result entry).
      void setUseSynchronousMode​(boolean useSynchronousMode)
      Specifies whether to operate in synchronous mode, in which at most one operation may be in progress at any time on a given connection.
      void setUseTCPNoDelay​(boolean useTCPNoDelay)
      Specifies whether to use the TCP_NODELAY option for the underlying sockets used by associated connections.
      java.lang.String toString()
      Retrieves a string representation of this LDAP connection.
      void toString​(java.lang.StringBuilder buffer)
      Appends a string representation of this LDAP connection to the provided buffer.
      boolean useKeepAlive()
      Indicates whether to use the SO_KEEPALIVE option for the underlying sockets used by associated connections.
      boolean useLinger()
      Indicates whether to use the SO_LINGER option for the underlying sockets used by associated connections.
      boolean usePooledSchema()
      Indicates whether to have connections that are part of a pool try to use shared schema information when reading data from the server (e.g., to select the appropriate matching rules for the attributes included in a search result entry).
      boolean useReuseAddress()
      Indicates whether to use the SO_REUSEADDR option for the underlying sockets used by associated connections.
      boolean useSchema()
      Indicates whether to try to use schema information when reading data from the server (e.g., to select the appropriate matching rules for the attributes included in a search result entry).
      boolean useSynchronousMode()
      Indicates whether to operate in synchronous mode, in which at most one operation may be in progress at any time on a given connection, which may allow it to operate more efficiently and without requiring a separate reader thread per connection.
      boolean useTCPNoDelay()
      Indicates whether to use the TCP_NODELAY option for the underlying sockets used by associated connections.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • PROPERTY_DEFAULT_ABANDON_ON_TIMEOUT

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_ABANDON_ON_TIMEOUT
        The name of a system property that can be used to specify the initial default value for the "abandon on timeout" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "false" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultAbandonTimeout".
      • PROPERTY_DEFAULT_BIND_WITH_DN_REQUIRES_PASSWORD

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_BIND_WITH_DN_REQUIRES_PASSWORD
        The name of a system property that can be used to specify the initial default value for the "bind with DN requires password" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "true" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions. defaultBindWithDNRequiresPassword".
      • PROPERTY_DEFAULT_CAPTURE_CONNECT_STACK_TRACE

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_CAPTURE_CONNECT_STACK_TRACE
        The name of a system property that can be used to specify the initial default value for the "capture connect stack trace" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "false" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultCaptureConnectStackTrace".
      • PROPERTY_DEFAULT_FOLLOW_REFERRALS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_FOLLOW_REFERRALS
        The name of a system property that can be used to specify the initial default value for the "follow referrals" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "false" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultFollowReferrals".
      • PROPERTY_DEFAULT_REFERRAL_HOP_LIMIT

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_REFERRAL_HOP_LIMIT
        The name of a system property that can be used to specify the maximum number of hops to make when following a referral. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. If this property is not set, then a default value of "5" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultReferralHopLimit".
      • PROPERTY_DEFAULT_USE_SCHEMA

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_USE_SCHEMA
        The name of a system property that can be used to specify the initial default value for the "use schema" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "false" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseSchema".
      • PROPERTY_DEFAULT_USE_POOLED_SCHEMA

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_USE_POOLED_SCHEMA
        The name of a system property that can be used to specify the initial default value for the "use pooled schema" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "false" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUsePooledSchema".
      • PROPERTY_DEFAULT_POOLED_SCHEMA_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_POOLED_SCHEMA_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default value for the pooled schema timeout, in milliseconds. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. If this property is not set, then a default value of "3600000" (3,600,000 milliseconds, or 1 hour) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultPooledSchemaTimeoutMillis".
      • PROPERTY_DEFAULT_USE_KEEPALIVE

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_USE_KEEPALIVE
        The name of a system property that can be used to specify the initial default value for the "use keepalive" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "true" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseKeepalive".
      • PROPERTY_DEFAULT_USE_LINGER

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_USE_LINGER
        The name of a system property that can be used to specify the initial default value for the "use linger" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "true" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseLinger".
      • PROPERTY_DEFAULT_LINGER_TIMEOUT_SECONDS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_LINGER_TIMEOUT_SECONDS
        The name of a system property that can be used to specify the initial default value for the linger timeout, in seconds. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. If this property is not set, then a default value of "5" (5 seconds) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultLingerTimeoutSeconds".
      • PROPERTY_DEFAULT_USE_REUSE_ADDRESS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_USE_REUSE_ADDRESS
        The name of a system property that can be used to specify the initial default value for the "use reuse address" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "true" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseReuseAddress".
      • PROPERTY_DEFAULT_USE_SYNCHRONOUS_MODE

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_USE_SYNCHRONOUS_MODE
        The name of a system property that can be used to specify the initial default value for the "use synchronous mode" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "false" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseSynchronousMode".
      • PROPERTY_DEFAULT_USE_TCP_NODELAY

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_USE_TCP_NODELAY
        The name of a system property that can be used to specify the initial default value for the "use TCP nodelay" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "true" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultUseTCPNoDelay".
      • PROPERTY_DEFAULT_CONNECT_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_CONNECT_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default connect timeout, in milliseconds. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. If this property is not set then a default value of "10000" (10,000 milliseconds, or ten seconds) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultConnectTimeoutMillis".
      • PROPERTY_DEFAULT_MAX_MESSAGE_SIZE_BYTES

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_MAX_MESSAGE_SIZE_BYTES
        The name of a system property that can be used to specify the initial default value for the maximum message size, in bytes. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. If this property is not set, then a default value of "20971520" (20 megabytes) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultMaxMessageSizeBytes".
      • PROPERTY_DEFAULT_RECEIVE_BUFFER_SIZE_BYTES

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_RECEIVE_BUFFER_SIZE_BYTES
        The name of a system property that can be used to specify the initial default value for the receive buffer size, in bytes. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. If this property is not set, then a default value of "0" (indicating that the JVM's default receive buffer size) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultReceiveBufferSizeBytes".
      • PROPERTY_DEFAULT_SEND_BUFFER_SIZE_BYTES

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_SEND_BUFFER_SIZE_BYTES
        The name of a system property that can be used to specify the initial default value for the send buffer size, in bytes. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. If this property is not set, then a default value of "0" (indicating that the JVM's default send buffer size) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk.LDAPConnectionOptions.defaultSendBufferSizeBytes".
      • PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default value for response timeouts, in milliseconds, for all types of operations. If this property is set at the time that this class is loaded, then its value must be parseable as an integer, and that value will override the values of any operation-specific properties. If this property is not set, then a default value of "300000" (300,000 milliseconds, or 5 minutes) will be assumed, but that may be overridden by operation-specific properties.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultResponseTimeoutMillis".
      • PROPERTY_DEFAULT_ADD_RESPONSE_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_ADD_RESPONSE_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default value for response timeouts, in milliseconds, for add operations. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. It will only be used if the PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS system property is not set, as that property will override this one. If neither of those properties is set, then a default value of "30000" (30,000 milliseconds, or 30 seconds) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultAddResponseTimeoutMillis".
      • PROPERTY_DEFAULT_BIND_RESPONSE_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_BIND_RESPONSE_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default value for response timeouts, in milliseconds, for bind operations. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. It will only be used if the PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS system property is not set, as that property will override this one. If neither of those properties is set, then a default value of "30000" (30,000 milliseconds, or 30 seconds) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultBindResponseTimeoutMillis".
      • PROPERTY_DEFAULT_COMPARE_RESPONSE_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_COMPARE_RESPONSE_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default value for response timeouts, in milliseconds, for compare operations. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. It will only be used if the PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS system property is not set, as that property will override this one. If neither of those properties is set, then a default value of "30000" (30,000 milliseconds, or 30 seconds) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultCompareResponseTimeoutMillis".
      • PROPERTY_DEFAULT_DELETE_RESPONSE_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_DELETE_RESPONSE_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default value for response timeouts, in milliseconds, for delete operations. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. It will only be used if the PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS system property is not set, as that property will override this one. If neither of those properties is set, then a default value of "30000" (30,000 milliseconds, or 30 seconds) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultDeleteResponseTimeoutMillis".
      • PROPERTY_DEFAULT_EXTENDED_RESPONSE_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_EXTENDED_RESPONSE_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default value for response timeouts, in milliseconds, for extended operations. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. It will only be used if the PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS system property is not set, as that property will override this one. If neither of those properties is set, then a default value of "300000" (300,000 milliseconds, or 5 minutes) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultExtendedResponseTimeoutMillis".

        Note that different timeouts may be set for specific types using a system property with this name immediately followed by a period and the request OID for the desired extended operation type. For example, the system property named "com.unboundid.ldap.sdk.LDAPConnectionOptions. defaultExtendedResponseTimeoutMillis.1.3.6.1.4.1.1466.20037" can be used to set a default response timeout for StartTLS extended operations.

        If neither the PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS nor the PROPERTY_DEFAULT_EXTENDED_RESPONSE_TIMEOUT_MILLIS property is set, then the following standard extended operation types will have a default timeout of 30,000 milliseconds (30 seconds) instead of 300,000 milliseconds (5 minutes), unless a property is defined to override the timeout for that specific type of extended operation:
        • Password Modify (1.3.6.1.4.1.4203.1.11.1)
        • StartTLS (1.3.6.1.4.1.1466.20037)
        • Who Am I? (1.3.6.1.4.1.4203.1.11.3)

        The same will also be true for the following extended operations specific to the UnboundID/Ping Identity Directory Server:
        • Deregister YubiKey OTP Device (1.3.6.1.4.1.30221.2.6.55)
        • End Administrative Session (1.3.6.1.4.1.30221.2.6.14)
        • Generate TOTP Shared Secret (1.3.6.1.4.1.30221.2.6.56)
        • Get Connection ID (1.3.6.1.4.1.30221.1.6.2)
        • Get Password Quality Requirements (1.3.6.1.4.1.30221.2.6.43)
        • Password Policy State (1.3.6.1.4.1.30221.1.6.1)
        • Register YubiKey OTP Device (1.3.6.1.4.1.30221.2.6.54)
        • Revoke TOTP Shared Secret (1.3.6.1.4.1.30221.2.6.58)
        • Start Administrative Session (1.3.6.1.4.1.30221.2.6.13)
        • Validate TOTP Password (1.3.6.1.4.1.30221.2.6.15)
      • PROPERTY_DEFAULT_MODIFY_RESPONSE_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_MODIFY_RESPONSE_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default value for response timeouts, in milliseconds, for modify operations. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. It will only be used if the PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS system property is not set, as that property will override this one. If neither of those properties is set, then a default value of "30000" (30,000 milliseconds, or 30 seconds) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultModifyResponseTimeoutMillis".
      • PROPERTY_DEFAULT_MODIFY_DN_RESPONSE_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_MODIFY_DN_RESPONSE_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default value for response timeouts, in milliseconds, for modify DN operations. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. It will only be used if the PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS system property is not set, as that property will override this one. If neither of those properties is set, then a default value of "30000" (30,000 milliseconds, or 30 seconds) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultModifyDNResponseTimeoutMillis".
      • PROPERTY_DEFAULT_SEARCH_RESPONSE_TIMEOUT_MILLIS

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_SEARCH_RESPONSE_TIMEOUT_MILLIS
        The name of a system property that can be used to specify the initial default value for response timeouts, in milliseconds, for search operations. If this property is set at the time that this class is loaded, then its value must be parseable as an integer. It will only be used if the PROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS system property is not set, as that property will override this one. If neither of those properties is set, then a default value of "300000" (300,000 milliseconds, or 5 minutes) will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultSearchResponseTimeoutMillis".
      • PROPERTY_DEFAULT_ALLOW_CONCURRENT_SOCKET_FACTORY_USE

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_ALLOW_CONCURRENT_SOCKET_FACTORY_USE
        The name of a system property that can be used to specify the default value for the "allow concurrent socket factory use" behavior. If this property is set at the time that this class is loaded, then its value must be either "true" or "false". If this property is not set, then a default value of "true" will be assumed.

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultAllowConcurrentSocketFactoryUse".
      • PROPERTY_DEFAULT_VERIFY_CERTIFICATE_HOSTNAMES

        @NotNull
        public static final java.lang.String PROPERTY_DEFAULT_VERIFY_CERTIFICATE_HOSTNAMES
        The name of a system property that can be used to indicate that the LDAP SDK should perform validation for certificate hostnames when negotiating a TLS session. By default, this validation will only be enabled if the setSSLSocketVerifier(com.unboundid.util.ssl.SSLSocketVerifier) method is called and provided with an HostNameSSLSocketVerifier instance. However, if this property is set with a value of "true", then connections will use a HostNameSSLSocketVerifier by default, and attempts to establish a secure connection will fail if the address used to establish the connection does not match any of the allowed addresses for that certificate (e.g., in its subject alternative name extension).

        The full name for this system property is "com.unboundid.ldap.sdk. LDAPConnectionOptions.defaultVerifyCertificateHostnames".
    • Constructor Detail

      • LDAPConnectionOptions

        public LDAPConnectionOptions()
        Creates a new set of LDAP connection options with the default settings.
    • Method Detail

      • duplicate

        @NotNull
        public LDAPConnectionOptions duplicate()
        Returns a duplicate of this LDAP connection options object that may be modified without impacting this instance.
        Returns:
        A duplicate of this LDAP connection options object that may be modified without impacting this instance.
      • autoReconnect

        @Deprecated
        public boolean autoReconnect()
        Deprecated.
        The use of auto-reconnect is strongly discouraged because it is inherently fragile and can only work under very limited circumstances. It is strongly recommended that a connection pool be used instead of the auto-reconnect option, even in cases where only a single connection is desired.
        Indicates whether associated connections should attempt to automatically reconnect to the target server if the connection is lost. Note that this option will not have any effect on pooled connections because defunct pooled connections will be replaced by newly-created connections rather than attempting to re-establish the existing connection.

        NOTE: The use of auto-reconnect is strongly discouraged because it is inherently fragile and can only work under very limited circumstances. It is strongly recommended that a connection pool be used instead of the auto-reconnect option, even in cases where only a single connection is desired.
        Returns:
        true if associated connections should attempt to automatically reconnect to the target server if the connection is lost, or false if not.
      • setAutoReconnect

        @Deprecated
        public void setAutoReconnect​(boolean autoReconnect)
        Deprecated.
        The use of auto-reconnect is strongly discouraged because it is inherently fragile and can only work under very limited circumstances. It is strongly recommended that a connection pool be used instead of the auto-reconnect option, even in cases where only a single connection is desired.
        Specifies whether associated connections should attempt to automatically reconnect to the target server if the connection is lost. Note that automatic reconnection will only be available for authenticated clients if the authentication mechanism used provides support for re-binding on a new connection. Also note that this option will not have any effect on pooled connections because defunct pooled connections will be replaced by newly-created connections rather than attempting to re-establish the existing connection. Further, auto-reconnect should not be used with connections that use StartTLS or some other mechanism to alter the state of the connection beyond authentication.

        NOTE: The use of auto-reconnect is strongly discouraged because it is inherently fragile and can only work under very limited circumstances. It is strongly recommended that a connection pool be used instead of the auto-reconnect option, even in cases where only a single connection is desired.
        Parameters:
        autoReconnect - Specifies whether associated connections should attempt to automatically reconnect to the target server if the connection is lost.
      • getNameResolver

        @NotNull
        public NameResolver getNameResolver()
        Retrieves the name resolver that should be used to resolve host names to IP addresses.
        Returns:
        The name resolver that should be used to resolve host names to IP addresses.
      • setNameResolver

        public void setNameResolver​(@Nullable
                                    NameResolver nameResolver)
        Sets the name resolver that should be used to resolve host names to IP addresses.
        Parameters:
        nameResolver - The name resolver that should be used to resolve host names to IP addresses.
      • bindWithDNRequiresPassword

        public boolean bindWithDNRequiresPassword()
        Indicates whether the SDK should allow simple bind operations that contain a bind DN but no password. Binds of this type may represent a security vulnerability in client applications because they may cause the client to believe that the user is properly authenticated when the server considers it to be an unauthenticated connection.
        Returns:
        true if the SDK should allow simple bind operations that contain a bind DN but no password, or false if not.
      • setBindWithDNRequiresPassword

        public void setBindWithDNRequiresPassword​(boolean bindWithDNRequiresPassword)
        Specifies whether the SDK should allow simple bind operations that contain a bind DN but no password.
        Parameters:
        bindWithDNRequiresPassword - Indicates whether the SDK should allow simple bind operations that contain a bind DN but no password.
      • captureConnectStackTrace

        public boolean captureConnectStackTrace()
        Indicates whether the LDAP SDK should capture a thread stack trace for each attempt made to establish a connection. If this is enabled, then the LDAPConnection.getConnectStackTrace() method may be used to retrieve the stack trace.
        Returns:
        true if a thread stack trace should be captured whenever a connection is established, or false if not.
      • setCaptureConnectStackTrace

        public void setCaptureConnectStackTrace​(boolean captureConnectStackTrace)
        Specifies whether the LDAP SDK should capture a thread stack trace for each attempt made to establish a connection.
        Parameters:
        captureConnectStackTrace - Indicates whether to capture a thread stack trace for each attempt made to establish a connection.
      • getConnectTimeoutMillis

        public int getConnectTimeoutMillis()
        Retrieves the maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up.
        Returns:
        The maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up, or zero to indicate that there should be no connect timeout.
      • setConnectTimeoutMillis

        public void setConnectTimeoutMillis​(int connectTimeoutMillis)
        Specifies the maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up. A value of zero indicates that there should be no connect timeout.
        Parameters:
        connectTimeoutMillis - The maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up.
      • getResponseTimeoutMillis

        public long getResponseTimeoutMillis()
        Retrieves the maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server. This may be overridden on a per-operation type basis, so the getResponseTimeoutMillis(OperationType) method should be used instead of this one.
        Returns:
        The maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server, or zero if there should not be any default timeout.
      • setResponseTimeoutMillis

        public void setResponseTimeoutMillis​(long responseTimeoutMillis)
        Specifies the maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout. Note that this will override any per-operation type and per-extended operation type timeouts that had previously been set.
        Parameters:
        responseTimeoutMillis - The maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server.
      • getResponseTimeoutMillis

        public long getResponseTimeoutMillis​(@NotNull
                                             OperationType operationType)
        Retrieves the maximum length of time in milliseconds that an operation of the specified type should be allowed to block while waiting for a response from the server. Note that for extended operations, the response timeout may be overridden on a per-request OID basis, so the getExtendedOperationResponseTimeoutMillis(String) method should be used instead of this one for extended operations.
        Parameters:
        operationType - The operation type for which to make the determination. It must not be null.
        Returns:
        The maximum length of time in milliseconds that an operation of the specified type should be allowed to block while waiting for a response from the server, or zero if there should not be any default timeout.
      • setResponseTimeoutMillis

        public void setResponseTimeoutMillis​(@NotNull
                                             OperationType operationType,
                                             long responseTimeoutMillis)
        Specifies the maximum length of time in milliseconds that an operation of the specified type should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
        Parameters:
        operationType - The operation type for which to set the response timeout. It must not be null.
        responseTimeoutMillis - The maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server.
      • getExtendedOperationResponseTimeoutMillis

        public long getExtendedOperationResponseTimeoutMillis​(@NotNull
                                                              java.lang.String requestOID)
        Retrieves the maximum length of time in milliseconds that an extended operation with the specified request OID should be allowed to block while waiting for a response from the server.
        Parameters:
        requestOID - The request OID for the extended operation for which to make the determination. It must not be null.
        Returns:
        The maximum length of time in milliseconds that the specified type of extended operation should be allowed to block while waiting for a response from the server, or zero if there should not be any default timeout.
      • setExtendedOperationResponseTimeoutMillis

        public void setExtendedOperationResponseTimeoutMillis​(@NotNull
                                                              java.lang.String requestOID,
                                                              long responseTimeoutMillis)
        Specifies the maximum length of time in milliseconds that an extended operation with the specified request OID should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.
        Parameters:
        requestOID - The request OID for the extended operation type for which to set the response timeout. It must not be null.
        responseTimeoutMillis - The maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server.
      • abandonOnTimeout

        public boolean abandonOnTimeout()
        Indicates whether the LDAP SDK should attempt to abandon any request for which no response is received in the maximum response timeout period.
        Returns:
        true if the LDAP SDK should attempt to abandon any request for which no response is received in the maximum response timeout period, or false if no abandon attempt should be made in this circumstance.
      • setAbandonOnTimeout

        public void setAbandonOnTimeout​(boolean abandonOnTimeout)
        Specifies whether the LDAP SDK should attempt to abandon any request for which no response is received in the maximum response timeout period.
        Parameters:
        abandonOnTimeout - Indicates whether the LDAP SDK should attempt to abandon any request for which no response is received in the maximum response timeout period.
      • useKeepAlive

        public boolean useKeepAlive()
        Indicates whether to use the SO_KEEPALIVE option for the underlying sockets used by associated connections.
        Returns:
        true if the SO_KEEPALIVE option should be used for the underlying sockets, or false if not.
      • setUseKeepAlive

        public void setUseKeepAlive​(boolean useKeepAlive)
        Specifies whether to use the SO_KEEPALIVE option for the underlying sockets used by associated connections. Changes to this setting will take effect only for new sockets, and not for existing sockets.
        Parameters:
        useKeepAlive - Indicates whether to use the SO_KEEPALIVE option for the underlying sockets used by associated connections.
      • useLinger

        public boolean useLinger()
        Indicates whether to use the SO_LINGER option for the underlying sockets used by associated connections.
        Returns:
        true if the SO_LINGER option should be used for the underlying sockets, or false if not.
      • getLingerTimeoutSeconds

        public int getLingerTimeoutSeconds()
        Retrieves the linger timeout in seconds that will be used if the SO_LINGER socket option is enabled.
        Returns:
        The linger timeout in seconds that will be used if the SO_LINGER socket option is enabled.
      • setUseLinger

        public void setUseLinger​(boolean useLinger,
                                 int lingerTimeoutSeconds)
        Specifies whether to use the SO_LINGER option for the underlying sockets used by associated connections. Changes to this setting will take effect only for new sockets, and not for existing sockets.
        Parameters:
        useLinger - Indicates whether to use the SO_LINGER option for the underlying sockets used by associated connections.
        lingerTimeoutSeconds - The linger timeout in seconds that should be used if this capability is enabled.
      • useReuseAddress

        public boolean useReuseAddress()
        Indicates whether to use the SO_REUSEADDR option for the underlying sockets used by associated connections.
        Returns:
        true if the SO_REUSEADDR option should be used for the underlying sockets, or false if not.
      • setUseReuseAddress

        public void setUseReuseAddress​(boolean useReuseAddress)
        Specifies whether to use the SO_REUSEADDR option for the underlying sockets used by associated connections. Changes to this setting will take effect only for new sockets, and not for existing sockets.
        Parameters:
        useReuseAddress - Indicates whether to use the SO_REUSEADDR option for the underlying sockets used by associated connections.
      • useSchema

        public boolean useSchema()
        Indicates whether to try to use schema information when reading data from the server (e.g., to select the appropriate matching rules for the attributes included in a search result entry).

        If the LDAP SDK is configured to make use of schema, then it may be able to more accurately perform client-side matching, including methods like Filter.matchesEntry(Entry) or Attribute.hasValue(String). If both useSchema and useSPooledSchema are false, then all client-side matching for attribute values will treat them as directory string values with a caseIgnoreMatch equality matching rule. If either useSchema or usePooledSchema is true, then the LDAP SDK may be able to use the attribute type definitions from that schema to determine the appropriate syntax and matching rules to use for client-side matching operations involving those attributes. Any attribute types that are not defined in the schema will still be treated as case-insensitive directory string values.
        Returns:
        true if schema should be used when reading data from the server, or false if not.
      • setUseSchema

        public void setUseSchema​(boolean useSchema)
        Specifies whether to try to use schema information when reading data from the server (e.g., to select the appropriate matching rules for the attributes included in a search result entry).

        If the LDAP SDK is configured to make use of schema, then it may be able to more accurately perform client-side matching, including methods like Filter.matchesEntry(Entry) or Attribute.hasValue(String). If both useSchema and useSPooledSchema are false, then all client-side matching for attribute values will treat them as directory string values with a caseIgnoreMatch equality matching rule. If either useSchema or usePooledSchema is true, then the LDAP SDK may be able to use the attribute type definitions from that schema to determine the appropriate syntax and matching rules to use for client-side matching operations involving those attributes. Any attribute types that are not defined in the schema will still be treated as case-insensitive directory string values.

        Note that calling this method with a value of true will also cause the usePooledSchema setting to be given a value of false, since the two values should not both be true at the same time.
        Parameters:
        useSchema - Indicates whether to try to use schema information when reading data from the server.
      • usePooledSchema

        public boolean usePooledSchema()
        Indicates whether to have connections that are part of a pool try to use shared schema information when reading data from the server (e.g., to select the appropriate matching rules for the attributes included in a search result entry). If this is true, then connections in a connection pool will share the same cached schema information in a way that attempts to reduce network bandwidth and connection establishment time (by avoiding the need for each connection to retrieve its own copy of the schema).

        If the LDAP SDK is configured to make use of schema, then it may be able to more accurately perform client-side matching, including methods like Filter.matchesEntry(Entry) or Attribute.hasValue(String). If both useSchema and useSPooledSchema are false, then all client-side matching for attribute values will treat them as directory string values with a caseIgnoreMatch equality matching rule. If either useSchema or usePooledSchema is true, then the LDAP SDK may be able to use the attribute type definitions from that schema to determine the appropriate syntax and matching rules to use for client-side matching operations involving those attributes. Any attribute types that are not defined in the schema will still be treated as case-insensitive directory string values.

        If pooled schema is to be used, then it may be configured to expire so that the schema may be periodically re-retrieved for new connections to allow schema updates to be incorporated. This behavior is controlled by the value returned by the getPooledSchemaTimeoutMillis() method.
        Returns:
        true if all connections in a connection pool should reference the same schema object, or false if each connection should retrieve its own copy of the schema.
      • setUsePooledSchema

        public void setUsePooledSchema​(boolean usePooledSchema)
        Indicates whether to have connections that are part of a pool try to use shared schema information when reading data from the server (e.g., to select the appropriate matching rules for the attributes included in a search result entry).

        If the LDAP SDK is configured to make use of schema, then it may be able to more accurately perform client-side matching, including methods like Filter.matchesEntry(Entry) or Attribute.hasValue(String). If both useSchema and useSPooledSchema are false, then all client-side matching for attribute values will treat them as directory string values with a caseIgnoreMatch equality matching rule. If either useSchema or usePooledSchema is true, then the LDAP SDK may be able to use the attribute type definitions from that schema to determine the appropriate syntax and matching rules to use for client-side matching operations involving those attributes. Any attribute types that are not defined in the schema will still be treated as case-insensitive directory string values.

        Note that calling this method with a value of true will also cause the useSchema setting to be given a value of false, since the two values should not both be true at the same time.
        Parameters:
        usePooledSchema - Indicates whether all connections in a connection pool should reference the same schema object rather than attempting to retrieve their own copy of the schema.
      • getPooledSchemaTimeoutMillis

        public long getPooledSchemaTimeoutMillis()
        Retrieves the maximum length of time in milliseconds that a pooled schema object should be considered fresh. If the schema referenced by a connection pool is at least this old, then the next connection attempt may cause a new version of the schema to be retrieved.

        This will only be used if the usePooledSchema method returns true. A value of zero indicates that the pooled schema will never expire.
        Returns:
        The maximum length of time, in milliseconds, that a pooled schema object should be considered fresh, or zero if pooled schema objects should never expire.
      • setPooledSchemaTimeoutMillis

        public void setPooledSchemaTimeoutMillis​(long pooledSchemaTimeoutMillis)
        Specifies the maximum length of time in milliseconds that a pooled schema object should be considered fresh.
        Parameters:
        pooledSchemaTimeoutMillis - The maximum length of time in milliseconds that a pooled schema object should be considered fresh. A value less than or equal to zero will indicate that pooled schema should never expire.
      • useSynchronousMode

        public boolean useSynchronousMode()
        Indicates whether to operate in synchronous mode, in which at most one operation may be in progress at any time on a given connection, which may allow it to operate more efficiently and without requiring a separate reader thread per connection. The LDAP SDK will not absolutely enforce this restriction, but when operating in this mode correct behavior cannot be guaranteed when multiple attempts are made to use a connection for multiple concurrent operations.

        Note that if synchronous mode is to be used, then this connection option must be set on the connection before any attempt is made to establish the connection. Once the connection has been established, then it will continue to operate in synchronous or asynchronous mode based on the options in place at the time it was connected.
        Returns:
        true if associated connections should operate in synchronous mode, or false if not.
      • setUseSynchronousMode

        public void setUseSynchronousMode​(boolean useSynchronousMode)
        Specifies whether to operate in synchronous mode, in which at most one operation may be in progress at any time on a given connection.

        Note that if synchronous mode is to be used, then this connection option must be set on the connection before any attempt is made to establish the connection. Once the connection has been established, then it will continue to operate in synchronous or asynchronous mode based on the options in place at the time it was connected.
        Parameters:
        useSynchronousMode - Indicates whether to operate in synchronous mode.
      • useTCPNoDelay

        public boolean useTCPNoDelay()
        Indicates whether to use the TCP_NODELAY option for the underlying sockets used by associated connections.
        Returns:
        true if the TCP_NODELAY option should be used for the underlying sockets, or false if not.
      • setUseTCPNoDelay

        public void setUseTCPNoDelay​(boolean useTCPNoDelay)
        Specifies whether to use the TCP_NODELAY option for the underlying sockets used by associated connections. Changes to this setting will take effect only for new sockets, and not for existing sockets.
        Parameters:
        useTCPNoDelay - Indicates whether to use the TCP_NODELAY option for the underlying sockets used by associated connections.
      • followReferrals

        public boolean followReferrals()
        Indicates whether associated connections should attempt to follow any referrals that they encounter.
        Returns:
        true if associated connections should attempt to follow any referrals that they encounter, or false if not.
      • setFollowReferrals

        public void setFollowReferrals​(boolean followReferrals)
        Specifies whether associated connections should attempt to follow any referrals that they encounter, using the referral connector for the associated connection.
        Parameters:
        followReferrals - Specifies whether associated connections should attempt to follow any referrals that they encounter.
      • getReferralHopLimit

        public int getReferralHopLimit()
        Retrieves the maximum number of hops that a connection should take when trying to follow a referral.
        Returns:
        The maximum number of hops that a connection should take when trying to follow a referral.
      • setReferralHopLimit

        public void setReferralHopLimit​(int referralHopLimit)
        Specifies the maximum number of hops that a connection should take when trying to follow a referral.
        Parameters:
        referralHopLimit - The maximum number of hops that a connection should take when trying to follow a referral. It must be greater than zero.
      • getReferralConnector

        @Nullable
        public ReferralConnector getReferralConnector()
        Retrieves the referral connector that will be used to establish and optionally authenticate connections to servers when attempting to follow referrals, if defined.
        Returns:
        The referral connector that will be used to establish and optionally authenticate connections to servers when attempting to follow referrals, or null if no specific referral connector has been configured and referral connections should be created using the same socket factory and bind request as the connection on which the referral was received.
      • setReferralConnector

        public void setReferralConnector​(@Nullable
                                         ReferralConnector referralConnector)
        Specifies the referral connector that should be used to establish and optionally authenticate connections to servers when attempting to follow referrals.
        Parameters:
        referralConnector - The referral connector that will be used to establish and optionally authenticate connections to servers when attempting to follow referrals. It may be null to indicate that the same socket factory and bind request as the connection on which the referral was received should be used to establish and authenticate connections for following referrals.
      • getMaxMessageSize

        public int getMaxMessageSize()
        Retrieves the maximum size in bytes for an LDAP message that a connection will attempt to read from the directory server. If it encounters an LDAP message that is larger than this size, then the connection will be terminated.
        Returns:
        The maximum size in bytes for an LDAP message that a connection will attempt to read from the directory server, or 0 if no limit will be enforced.
      • setMaxMessageSize

        public void setMaxMessageSize​(int maxMessageSizeBytes)
        Specifies the maximum size in bytes for an LDAP message that a connection will attempt to read from the directory server. If it encounters an LDAP message that is larger than this size, then the connection will be terminated.
        Parameters:
        maxMessageSizeBytes - The maximum size in bytes for an LDAP message that a connection will attempt to read from the directory server. A value less than or equal to zero indicates that no limit should be enforced.
      • getConnectionLogger

        @Nullable
        public LDAPConnectionLogger getConnectionLogger()
        Retrieves the logger that should be used to record information about requests sent and responses received over connections with this set of connection options.
        Returns:
        The logger that should be used to record information about the requests sent and responses received over connection with this set of options, or null if no logging should be performed.
      • setConnectionLogger

        public void setConnectionLogger​(@Nullable
                                        LDAPConnectionLogger connectionLogger)
        Specifies the logger that should be used to record information about requests sent and responses received over connections with this set of connection options.
        Parameters:
        connectionLogger - The logger that should be used to record information about the requests sent and responses received over connection with this set of options. It may be null if no logging should be performed.
      • getDisconnectHandler

        @Nullable
        public DisconnectHandler getDisconnectHandler()
        Retrieves the disconnect handler to use for associated connections.
        Returns:
        the disconnect handler to use for associated connections, or null if none is defined.
      • setDisconnectHandler

        public void setDisconnectHandler​(@Nullable
                                         DisconnectHandler handler)
        Specifies the disconnect handler to use for associated connections.
        Parameters:
        handler - The disconnect handler to use for associated connections.
      • getReceiveBufferSize

        public int getReceiveBufferSize()
        Retrieves the socket receive buffer size, in bytes, that should be requested when establishing a connection.
        Returns:
        The socket receive buffer size, in bytes, that should be requested when establishing a connection, or zero if the JVM's default size should be used.
      • setReceiveBufferSize

        public void setReceiveBufferSize​(int receiveBufferSizeBytes)
        Specifies the socket receive buffer size, in bytes, that should be requested when establishing a connection.
        Parameters:
        receiveBufferSizeBytes - The socket receive buffer size, in bytes, that should be requested when establishing a connection, or zero if the JVM's default size should be used.
      • getSendBufferSize

        public int getSendBufferSize()
        Retrieves the socket send buffer size, in bytes, that should be requested when establishing a connection.
        Returns:
        The socket send buffer size, in bytes, that should be requested when establishing a connection, or zero if the JVM's default size should be used.
      • setSendBufferSize

        public void setSendBufferSize​(int sendBufferSizeBytes)
        Specifies the socket send buffer size, in bytes, that should be requested when establishing a connection.
        Parameters:
        sendBufferSizeBytes - The socket send buffer size, in bytes, that should be requested when establishing a connection, or zero if the JVM's default size should be used.
      • allowConcurrentSocketFactoryUse

        public boolean allowConcurrentSocketFactoryUse()
        Indicates whether to allow a socket factory instance (which may be shared across multiple connections) to be used create multiple sockets concurrently. In general, socket factory implementations are threadsafe and can be to create multiple connections simultaneously across separate threads, but this is known to not be the case in some VM implementations (e.g., SSL socket factories in IBM JVMs). This setting may be used to indicate whether concurrent socket creation attempts should be allowed (which may allow for better and more consistent performance, especially in cases where a connection attempt fails due to a timeout) or prevented (which may be necessary for non-threadsafe socket factory implementations).
        Returns:
        true if multiple threads should be able to concurrently use the same socket factory instance, or false if Java synchronization should be used to ensure that no more than one thread is allowed to use a socket factory at any given time.
      • setAllowConcurrentSocketFactoryUse

        public void setAllowConcurrentSocketFactoryUse​(boolean allowConcurrentSocketFactoryUse)
        Specifies whether to allow a socket factory instance (which may be shared across multiple connections) to be used create multiple sockets concurrently. In general, socket factory implementations are threadsafe and can be to create multiple connections simultaneously across separate threads, but this is known to not be the case in some VM implementations (e.g., SSL socket factories in IBM JVMs). This setting may be used to indicate whether concurrent socket creation attempts should be allowed (which may allow for better and more consistent performance, especially in cases where a connection attempt fails due to a timeout) or prevented (which may be necessary for non-threadsafe socket factory implementations).
        Parameters:
        allowConcurrentSocketFactoryUse - Indicates whether to allow a socket factory instance to be used to create multiple sockets concurrently.
      • getSSLSocketVerifier

        @NotNull
        public SSLSocketVerifier getSSLSocketVerifier()
        Retrieves the SSLSocketVerifier that will be used to perform additional validation for any newly-created SSLSocket instances.
        Returns:
        The SSLSocketVerifier that will be used to perform additional validation for any newly-created SSLSocket instances.
      • setSSLSocketVerifier

        public void setSSLSocketVerifier​(@Nullable
                                         SSLSocketVerifier sslSocketVerifier)
        Specifies the SSLSocketVerifier that will be used to perform additional validation for any newly-created SSLSocket instances.
        Parameters:
        sslSocketVerifier - The SSLSocketVerifier that will be used to perform additional validation for any newly-created SSLSocket instances.
      • toString

        @NotNull
        public java.lang.String toString()
        Retrieves a string representation of this LDAP connection.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representation of this LDAP connection.
      • toString

        public void toString​(@NotNull
                             java.lang.StringBuilder buffer)
        Appends a string representation of this LDAP connection to the provided buffer.
        Parameters:
        buffer - The buffer to which to append a string representation of this LDAP connection.