@Mutable @ThreadSafety(level=NOT_THREADSAFE) public final class LDAPConnectionOptions extends java.lang.Object
DisconnectHandler
that should be used to receive
notification if connection is disconnected for any reason. By default,
no DisconnectHandler
will be used.UnsolicitedNotificationHandler
that should be used to
receive notification about any unsolicited notifications returned by
the server. By default, no UnsolicitedNotificationHandler
will
be used.SSLSocket
instances created. By
default, no special verification will be performed.Constructor and Description |
---|
LDAPConnectionOptions()
Creates a new set of LDAP connection options with the default settings.
|
Modifier and Type | Method and 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. 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.
|
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.
|
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 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.
|
SSLSocketVerifier |
getSSLSocketVerifier()
Retrieves the
SSLSocketVerifier that will be used to perform
additional validation for any newly-created SSLSocket instances. |
UnsolicitedNotificationHandler |
getUnsolicitedNotificationHandler()
Retrieves the unsolicited notification handler to use for associated
connections.
|
void |
setAbandonOnTimeout(boolean abandonOnTimeout)
Specifies whether the LDAP SDK should attempt to abandon any request for
which no response is received in the maximum response timeout period.
|
void |
setAllowConcurrentSocketFactoryUse(boolean allowConcurrentSocketFactoryUse)
Specifies whether to allow a socket factory instance (which may be shared
across multiple connections) to be used create multiple sockets
concurrently.
|
void |
setAutoReconnect(boolean autoReconnect)
Deprecated.
The use of auto-reconnect is strongly discouraged because it
is inherently fragile and can only work under very limited
circumstances. 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.
|
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 |
setPooledSchemaTimeoutMillis(long pooledSchemaTimeout)
Specifies the maximum length of time in milliseconds that a pooled schema
object should be considered fresh.
|
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 |
setSSLSocketVerifier(SSLSocketVerifier sslSocketVerifier)
Specifies the
SSLSocketVerifier that will be used to perform
additional validation for any newly-created SSLSocket instances. |
void |
setUnsolicitedNotificationHandler(UnsolicitedNotificationHandler handler)
Specifies the unsolicited notification handler to use for associated
connections.
|
void |
setUseKeepAlive(boolean useKeepAlive)
Specifies whether to use the SO_KEEPALIVE option for the underlying sockets
used by associated connections.
|
void |
setUseLinger(boolean useLinger,
int lingerTimeout)
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.
|
public LDAPConnectionOptions()
public LDAPConnectionOptions duplicate()
@Deprecated public boolean autoReconnect()
true
if associated connections should attempt to
automatically reconnect to the target server if the connection is
lost, or false
if not.@Deprecated public void setAutoReconnect(boolean autoReconnect)
autoReconnect
- Specifies whether associated connections should
attempt to automatically reconnect to the target
server if the connection is lost.public boolean bindWithDNRequiresPassword()
true
if the SDK should allow simple bind operations that
contain a bind DN but no password, or false
if not.public void setBindWithDNRequiresPassword(boolean bindWithDNRequiresPassword)
bindWithDNRequiresPassword
- Indicates whether the SDK should allow
simple bind operations that contain a
bind DN but no password.public boolean captureConnectStackTrace()
LDAPConnection.getConnectStackTrace()
method may be used to
retrieve the stack trace.true
if a thread stack trace should be captured whenever a
connection is established, or false
if not.public void setCaptureConnectStackTrace(boolean captureConnectStackTrace)
captureConnectStackTrace
- Indicates whether to capture a thread
stack trace for each attempt made to
establish a connection.public int getConnectTimeoutMillis()
public void setConnectTimeoutMillis(int connectTimeout)
connectTimeout
- The maximum length of time in milliseconds that a
connection attempt should be allowed to continue
before giving up.public long getResponseTimeoutMillis()
public void setResponseTimeoutMillis(long responseTimeout)
responseTimeout
- The maximum length of time in milliseconds that an
operation should be allowed to block while waiting
for a response from the server.public boolean abandonOnTimeout()
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.public void setAbandonOnTimeout(boolean abandonOnTimeout)
abandonOnTimeout
- Indicates whether the LDAP SDK should attempt to
abandon any request for which no response is
received in the maximum response timeout period.public boolean useKeepAlive()
true
if the SO_KEEPALIVE option should be used for the
underlying sockets, or false
if not.public void setUseKeepAlive(boolean useKeepAlive)
useKeepAlive
- Indicates whether to use the SO_KEEPALIVE option for
the underlying sockets used by associated
connections.public boolean useLinger()
true
if the SO_LINGER option should be used for the
underlying sockets, or false
if not.public int getLingerTimeoutSeconds()
public void setUseLinger(boolean useLinger, int lingerTimeout)
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.public boolean useReuseAddress()
true
if the SO_REUSEADDR option should be used for the
underlying sockets, or false
if not.public void setUseReuseAddress(boolean useReuseAddress)
useReuseAddress
- Indicates whether to use the SO_REUSEADDR option
for the underlying sockets used by associated
connections.public boolean useSchema()
true
if schema should be used when reading data from the
server, or false
if not.public void setUseSchema(boolean useSchema)
true
will also cause
the usePooledSchema
setting to be given a value of false, since
the two values should not both be true
at the same time.useSchema
- Indicates whether to try to use schema information when
reading data from the server.public boolean usePooledSchema()
true
, then connections in a
connection pool will share the same cached schema information in a way that
attempts to reduce network bandwidth and connection establishment time (by
avoiding the need for each connection to retrieve its own copy of the
schema).
getPooledSchemaTimeoutMillis()
method.true
if all connections in a connection pool should
reference the same schema object, or false
if each
connection should retrieve its own copy of the schema.public void setUsePooledSchema(boolean usePooledSchema)
true
will also cause
the useSchema
setting to be given a value of false, since the two
values should not both be true
at the same time.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.public long getPooledSchemaTimeoutMillis()
usePooledSchema
method returns
true
. A value of zero indicates that the pooled schema will never
expire.public void setPooledSchemaTimeoutMillis(long pooledSchemaTimeout)
pooledSchemaTimeout
- 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.public boolean useSynchronousMode()
true
if associated connections should operate in
synchronous mode, or false
if not.public void setUseSynchronousMode(boolean useSynchronousMode)
useSynchronousMode
- Indicates whether to operate in synchronous
mode.public boolean useTCPNoDelay()
true
if the TCP_NODELAY option should be used for the
underlying sockets, or false
if not.public void setUseTCPNoDelay(boolean useTCPNoDelay)
useTCPNoDelay
- Indicates whether to use the TCP_NODELAY option for
the underlying sockets used by associated
connections.public boolean followReferrals()
true
if associated connections should attempt to follow
any referrals that they encounter, or false
if not.public void setFollowReferrals(boolean followReferrals)
followReferrals
- Specifies whether associated connections should
attempt to follow any referrals that they
encounter.public int getReferralHopLimit()
public void setReferralHopLimit(int referralHopLimit)
referralHopLimit
- The maximum number of hops that a connection
should take when trying to follow a referral. It
must be greater than zero.public ReferralConnector getReferralConnector()
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.public void setReferralConnector(ReferralConnector referralConnector)
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.public int getMaxMessageSize()
public void setMaxMessageSize(int maxMessageSize)
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.public DisconnectHandler getDisconnectHandler()
null
if none is defined.public void setDisconnectHandler(DisconnectHandler handler)
handler
- The disconnect handler to use for associated connections.public UnsolicitedNotificationHandler getUnsolicitedNotificationHandler()
null
if none is defined.public void setUnsolicitedNotificationHandler(UnsolicitedNotificationHandler handler)
handler
- The unsolicited notification handler to use for associated
connections.public int getReceiveBufferSize()
public void setReceiveBufferSize(int receiveBufferSize)
receiveBufferSize
- The socket receive buffer size that should be
requested when establishing a connection, or
zero if the default size should be used.public int getSendBufferSize()
public void setSendBufferSize(int sendBufferSize)
sendBufferSize
- The socket send buffer size that should be
requested when establishing a connection, or zero
if the default size should be used.public boolean allowConcurrentSocketFactoryUse()
true
if multiple threads should be able to concurrently
use the same socket factory instance, or false
if Java
synchronization should be used to ensure that no more than one
thread is allowed to use a socket factory at any given time.public void setAllowConcurrentSocketFactoryUse(boolean allowConcurrentSocketFactoryUse)
allowConcurrentSocketFactoryUse
- Indicates whether to allow a
socket factory instance to be used
to create multiple sockets
concurrently.public SSLSocketVerifier getSSLSocketVerifier()
SSLSocketVerifier
that will be used to perform
additional validation for any newly-created SSLSocket
instances.SSLSocketVerifier
that will be used to perform
additional validation for any newly-created SSLSocket
instances.public void setSSLSocketVerifier(SSLSocketVerifier sslSocketVerifier)
SSLSocketVerifier
that will be used to perform
additional validation for any newly-created SSLSocket
instances.sslSocketVerifier
- The SSLSocketVerifier
that will be used
to perform additional validation for any
newly-created SSLSocket
instances.public java.lang.String toString()
toString
in class java.lang.Object
public void toString(java.lang.StringBuilder buffer)
buffer
- The buffer to which to append a string representation of
this LDAP connection.