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 which 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 60,000 milliseconds (1 minute) will be used.
• A value which specifies the default timeout in milliseconds that the SDK should wait for a response from the server before failing. By default, a timeout of 300,000 milliseconds (5 minutes) will be used.
• 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 20971520 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, 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.

Constructor Summary

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

Method Summary

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	autoReconnect() Indicates whether associated connections should attempt to automatically reconnect to the target server if the connection is lost.
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.
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.
int	getReceiveBufferSize() Retrieves the socket receive buffer size 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.
int	getSendBufferSize() Retrieves the socket send buffer size that should be requested when establishing a connection.
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	setAutoReconnect(boolean autoReconnect) Specifies whether associated connections should attempt to automatically reconnect to the target server if the connection is lost.
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 connectTimeout) 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	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 maxMessageSize) Specifies the maximum size in bytes for an LDAP message that a connection will attempt to read from the directory server.
void	setReceiveBufferSize(int receiveBufferSize) Specifies the socket receive buffer size 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 responseTimeout) 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	setSendBufferSize(int sendBufferSize) Specifies the socket send buffer size that should be requested when establishing a connection.
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 lingerTimeout) Specifies whether to use the SO_LINGER option for the underlying sockets used by associated connections.
void	setUseReuseAddress(boolean useReuseAddress) Specifies whether to use the SO_KEEPALIVE 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 SO_KEEPALIVE 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	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

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

public boolean autoReconnect()

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.

Returns:

true if associated connections should attempt to automatically reconnect to the target server if the connection is lost, or false if not.

setAutoReconnect

public void setAutoReconnect(boolean autoReconnect)

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.

Parameters:

autoReconnect - Specifies whether associated connections should attempt to automatically reconnect to the target server if the connection is lost.

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 connectTimeout)

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:

connectTimeout - 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 basis.

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 responseTimeout)

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.

Parameters:

responseTimeout - 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 lingerTimeout)

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.

lingerTimeout - 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_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:

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).

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).

Parameters:

useSchema - Indicates whether to try to use schema information when reading data from the server.

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 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:

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

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 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 maxMessageSize)

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:

maxMessageSize - 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 that should be requested when establishing a connection.

Returns:

The socket receive buffer size that should be requested when establishing a connection, or zero if the default size should be used.

setReceiveBufferSize

public void setReceiveBufferSize(int receiveBufferSize)

Specifies the socket receive buffer size that should be requested when establishing a connection.

Parameters:

receiveBufferSize - The socket receive buffer size that should be requested when establishing a connection, or zero if the default size should be used.

getSendBufferSize

public int getSendBufferSize()

Retrieves the socket send buffer size that should be requested when establishing a connection.

Returns:

The socket send buffer size that should be requested when establishing a connection, or zero if the default size should be used.

setSendBufferSize

public void setSendBufferSize(int sendBufferSize)

Specifies the socket send buffer size that should be requested when establishing a connection.

Parameters:

sendBufferSize - The socket send buffer size that should be requested when establishing a connection, or zero if the default size should be used.

toString

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(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.