Package com.unboundid.ldap.sdk
Class LDAPConnectionOptions
- java.lang.Object
-
- com.unboundid.ldap.sdk.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
DisconnectHandler
that should be used to receive notification if connection is disconnected for any reason. By default, noDisconnectHandler
will be used. - The
UnsolicitedNotificationHandler
that should be used to receive notification about any unsolicited notifications returned by the server. By default, noUnsolicitedNotificationHandler
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.
-
-
Field Summary
Fields Modifier and Type Field Description static NameResolver
DEFAULT_NAME_RESOLVER
The default name resolver that will be used to resolve host names to IP addresses.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.static 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.
-
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.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 theSSLSocketVerifier
that will be used to perform additional validation for any newly-createdSSLSocket
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
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 theSSLSocketVerifier
that will be used to perform additional validation for any newly-createdSSLSocket
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.
-
-
-
Field Detail
-
PROPERTY_DEFAULT_ABANDON_ON_TIMEOUT
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 thePROPERTY_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
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 thePROPERTY_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
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 thePROPERTY_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
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 thePROPERTY_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
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 thePROPERTY_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 thePROPERTY_DEFAULT_RESPONSE_TIMEOUT_MILLIS
nor thePROPERTY_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
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 thePROPERTY_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
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 thePROPERTY_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
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 thePROPERTY_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".
-
DEFAULT_NAME_RESOLVER
public static final NameResolver DEFAULT_NAME_RESOLVER
The default name resolver that will be used to resolve host names to IP addresses.
-
PROPERTY_DEFAULT_ALLOW_CONCURRENT_SOCKET_FACTORY_USE
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".
-
-
Constructor Detail
-
LDAPConnectionOptions
public LDAPConnectionOptions()
Creates a new set of LDAP connection options with the default settings.
-
-
Method Detail
-
duplicate
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, orfalse
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
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(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, orfalse
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 theLDAPConnection.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, orfalse
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 thegetResponseTimeoutMillis(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(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 thegetExtendedOperationResponseTimeoutMillis(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 benull
.- 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(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 benull
.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(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 benull
.- 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(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 benull
.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, orfalse
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, orfalse
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, orfalse
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, orfalse
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 likeFilter.matchesEntry(Entry)
orAttribute.hasValue(String)
. If bothuseSchema
anduseSPooledSchema
arefalse
, then all client-side matching for attribute values will treat them as directory string values with a caseIgnoreMatch equality matching rule. If eitheruseSchema
orusePooledSchema
istrue
, 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, orfalse
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 likeFilter.matchesEntry(Entry)
orAttribute.hasValue(String)
. If bothuseSchema
anduseSPooledSchema
arefalse
, then all client-side matching for attribute values will treat them as directory string values with a caseIgnoreMatch equality matching rule. If eitheruseSchema
orusePooledSchema
istrue
, 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 oftrue
will also cause theusePooledSchema
setting to be given a value of false, since the two values should not both betrue
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 istrue
, 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 likeFilter.matchesEntry(Entry)
orAttribute.hasValue(String)
. If bothuseSchema
anduseSPooledSchema
arefalse
, then all client-side matching for attribute values will treat them as directory string values with a caseIgnoreMatch equality matching rule. If eitheruseSchema
orusePooledSchema
istrue
, 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 thegetPooledSchemaTimeoutMillis()
method.- Returns:
true
if all connections in a connection pool should reference the same schema object, orfalse
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 likeFilter.matchesEntry(Entry)
orAttribute.hasValue(String)
. If bothuseSchema
anduseSPooledSchema
arefalse
, then all client-side matching for attribute values will treat them as directory string values with a caseIgnoreMatch equality matching rule. If eitheruseSchema
orusePooledSchema
istrue
, 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 oftrue
will also cause theuseSchema
setting to be given a value of false, since the two values should not both betrue
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 theusePooledSchema
method returnstrue
. 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, orfalse
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, orfalse
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, orfalse
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
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(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 benull
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.
-
getDisconnectHandler
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(DisconnectHandler handler)
Specifies the disconnect handler to use for associated connections.- Parameters:
handler
- The disconnect handler to use for associated connections.
-
getUnsolicitedNotificationHandler
public UnsolicitedNotificationHandler getUnsolicitedNotificationHandler()
Retrieves the unsolicited notification handler to use for associated connections.- Returns:
- The unsolicited notification handler to use for associated
connections, or
null
if none is defined.
-
setUnsolicitedNotificationHandler
public void setUnsolicitedNotificationHandler(UnsolicitedNotificationHandler handler)
Specifies the unsolicited notification handler to use for associated connections.- Parameters:
handler
- The unsolicited notification 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, orfalse
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
public SSLSocketVerifier getSSLSocketVerifier()
Retrieves theSSLSocketVerifier
that will be used to perform additional validation for any newly-createdSSLSocket
instances.- Returns:
- The
SSLSocketVerifier
that will be used to perform additional validation for any newly-createdSSLSocket
instances.
-
setSSLSocketVerifier
public void setSSLSocketVerifier(SSLSocketVerifier sslSocketVerifier)
Specifies theSSLSocketVerifier
that will be used to perform additional validation for any newly-createdSSLSocket
instances.- Parameters:
sslSocketVerifier
- TheSSLSocketVerifier
that will be used to perform additional validation for any newly-createdSSLSocket
instances.
-
toString
public java.lang.String toString()
Retrieves a string representation of this LDAP connection.- Overrides:
toString
in classjava.lang.Object
- Returns:
- A string representation of this LDAP connection.
-
toString
public void toString(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.
-
-