public final class LdapConnectionFactory extends Object implements ConnectionFactory
connect timeout
SSL_OPTIONS
option along with SSL_USE_STARTTLS
set to false
SSL_OPTIONS
option along with
SSL_USE_STARTTLS
set to true
AUTHN_BIND_REQUEST
option is specified
HEARTBEAT_ENABLED
option, and none of steps 2-4 were performed,
then an initial heart-beat is sent in order to determine whether the directory service is available.
ConnectionException
generated and published to any registered ConnectionEventListener
s. Note
however, that heart-beats will only be sent when the connection is determined to be reasonably idle: there is no
point in sending heart-beats if the connection has recently received a response. A connection is deemed to be idle
if no response has been received during a period equivalent to half the heart-beat interval.
The LDAP protocol specifically precludes clients from performing operations while bind or startTLS requests are being performed. Likewise, a bind or startTLS request will cause active operations to be aborted. This factory coordinates heart-beats with bind or startTLS requests, ensuring that they are not performed concurrently. Specifically, bind and startTLS requests are queued up while a heart-beat is pending, and heart-beats are not sent at all while there are pending bind or startTLS requests.
Modifier and Type | Field and Description |
---|---|
static Option<BindRequest> |
AUTHN_BIND_REQUEST
Configures the connection factory to return pre-authenticated connections using the specified
BindRequest . |
static Option<Supplier<BindRequest>> |
AUTHN_BIND_REQUEST_FACTORY
Configures the connection factory to return pre-authenticated connections using
BindRequest provided by
the specified Supplier . |
static Option<Duration> |
CONNECT_TIMEOUT
Specifies the connect timeout spcified.
|
static Option<DecodeOptions> |
DECODE_OPTIONS
Sets the decoding options which will be used to control how requests and responses are decoded.
|
static Option<Boolean> |
HEARTBEAT_ENABLED
Configures the connection factory to periodically send "heart-beat" or "keep-alive" requests to the Directory
Server.
|
static Option<Duration> |
HEARTBEAT_INTERVAL
Specifies the time between successive heart-beat requests (default interval is 10 seconds).
|
static Option<ScheduledExecutorService> |
HEARTBEAT_SCHEDULER
Specifies the scheduler which will be used for periodically sending heart-beat requests.
|
static Option<SearchRequest> |
HEARTBEAT_SEARCH_REQUEST
Specifies the parameters of the search request that will be used for heart-beats.
|
static Option<Duration> |
HEARTBEAT_TIMEOUT
Specifies the timeout for heart-beat requests, after which the remote Directory Server will be deemed to be
unavailable (default timeout is 3 seconds).
|
static Option<IntConsumer> |
PROBE_BYTES_READ
Callback invoked each time this server read bytes from the network.
|
static Option<IntConsumer> |
PROBE_BYTES_WRITTEN
Callback invoked each time this server write bytes to the network.
|
static Option<Duration> |
REQUEST_TIMEOUT
Specifies the operation timeout.
|
static Option<Boolean> |
SO_KEEPALIVE
Specifies the value of the
SO_KEEPALIVE socket option for new connections. |
static Option<Integer> |
SO_LINGER_IN_SECONDS
Specifies the value of the
SO_LINGER socket option for new connections. |
static Option<Boolean> |
SO_REUSE_ADDRESS
Specifies the value of the
SO_REUSEADDR socket option for new connections. |
static Option<SslOptions> |
SSL_OPTIONS
Specifies the options to use for the SSL support or
null if SSL is disabled. |
static Option<Boolean> |
SSL_USE_STARTTLS
Specifies whether SSL or StartTLS should be used for securing connections when an SSL context is specified.
|
static Option<Boolean> |
TCP_NO_DELAY
Specifies the value of the
TCP_NODELAY socket option for new connections. |
static Option<String> |
TRANSPORT_PROVIDER
Specifies the name of the provider to use for transport.
|
static Option<ClassLoader> |
TRANSPORT_PROVIDER_CLASS_LOADER
Specifies the class loader which will be used to load the
TransportProvider . |
Constructor and Description |
---|
LdapConnectionFactory(LdapClient ldapClient)
Creates a new LDAP connection factory which can be used to create LDAP connections to the Directory Server at the
provided host and port number.
|
LdapConnectionFactory(String host,
int port)
Creates a new LDAP connection factory which can be used to create LDAP connections to the Directory Server at the
provided host and port number.
|
LdapConnectionFactory(String host,
int port,
Options options)
Creates a new LDAP connection factory which can be used to create LDAP connections to the Directory Server at the
provided host and port number.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
Releases any resources associated with this connection factory.
|
Connection |
getConnection()
Returns a connection to the Directory Server associated with this
connection factory.
|
Promise<Connection,LdapException> |
getConnectionAsync()
Asynchronously obtains a connection to the Directory Server associated
with this connection factory.
|
public static final Option<BindRequest> AUTHN_BIND_REQUEST
BindRequest
. The connections returned by the connection factory will support all operations with the exception
of Bind requests. Attempts to perform a Bind will result in an UnsupportedOperationException
.
If the Bind request fails for some reason (e.g. invalid credentials), then the connection attempt will fail and
an LdapException
will be thrown.
public static final Option<Supplier<BindRequest>> AUTHN_BIND_REQUEST_FACTORY
BindRequest
provided by
the specified Supplier
. The connections returned by the connection factory will support all operations
with the exception of Bind requests. Attempts to perform a Bind will result in an
UnsupportedOperationException
.
If the Bind request fails for some reason (e.g. invalid credentials), then the connection attempt will fail and
an LdapException
will be thrown.
public static final Option<Duration> CONNECT_TIMEOUT
TimeoutResultException
error result will be
returned.
The default operation timeout is 10 seconds and may be configured using the org.forgerock.opendj.io.connectTimeout
property. A timeout setting of 0 causes the OS connect timeout to be
used.
public static final Option<Boolean> HEARTBEAT_ENABLED
Before returning new connections to the application the factory will first send an initial heart-beat request in order to determine that the remote server is responsive. If the heart-beat request fails or is too slow to respond then the connection is closed immediately and an error returned to the client.
Once a connection has been established successfully (including the initial heart-beat request), the connection
factory will periodically send heart-beat requests on the connection based on the configured heart-beat interval.
If the Directory Server is too slow to respond to the heart-beat then the server is assumed to be down and an
appropriate ConnectionException
generated and published to any registered
ConnectionEventListener
s. Note however, that heart-beat requests will only be sent when the connection
is determined to be reasonably idle: there is no point in sending heart-beats if the connection has recently
received a response. A connection is deemed to be idle if no response has been received during a period
equivalent to half the heart-beat interval.
The LDAP protocol specifically precludes clients from performing operations while bind or startTLS requests are being performed. Likewise, a bind or startTLS request will cause active operations to be aborted. The LDAP connection factory coordinates heart-beats with bind or startTLS requests, ensuring that they are not performed concurrently. Specifically, bind and startTLS requests are queued up while a heart-beat is pending, and heart-beats are not sent at all while there are pending bind or startTLS requests.
public static final Option<Duration> HEARTBEAT_INTERVAL
HEARTBEAT_ENABLED
is set to true
.HEARTBEAT_ENABLED
public static final Option<ScheduledExecutorService> HEARTBEAT_SCHEDULER
HEARTBEAT_ENABLED
is set to true
.HEARTBEAT_ENABLED
public static final Option<Duration> HEARTBEAT_TIMEOUT
HEARTBEAT_ENABLED
is set to
true
. If a request timeout
is also set then the lower of the two will be used
for sending heart-beats.HEARTBEAT_ENABLED
public static final Option<Duration> REQUEST_TIMEOUT
TimeoutResultException
error result returned. A
timeout setting of 0 disables operation timeout limits.
The default operation timeout is 0 (no timeout) and may be configured using the org.forgerock.opendj.io.requestTimeout
property or the deprecated org.forgerock.opendj.io.timeout
property.
public static final Option<Boolean> SSL_USE_STARTTLS
By default SSL will be used in preference to StartTLS.
public static final Option<SearchRequest> HEARTBEAT_SEARCH_REQUEST
HEARTBEAT_ENABLED
is set to true
.HEARTBEAT_ENABLED
public static final Option<ClassLoader> TRANSPORT_PROVIDER_CLASS_LOADER
TransportProvider
.
By default the default class loader will be used.
The transport provider is loaded using java.util.ServiceLoader
,
the JDK service-provider loading facility. The provider must be
accessible from the same class loader that was initially queried to
locate the configuration file; note that this is not necessarily the
class loader from which the file was actually loaded. This method allows
to provide a class loader to be used for loading the provider.
public static final Option<String> TRANSPORT_PROVIDER
Transport providers implement TransportProvider
interface.
The name should correspond to the name of an existing provider, as
returned by TransportProvider#getName()
method.
public static final Option<Boolean> TCP_NO_DELAY
TCP_NODELAY
socket option for new connections.
The default setting is true
and may be configured using the
org.forgerock.opendj.transport.tcpNoDelay
property.
public static final Option<Boolean> SO_REUSE_ADDRESS
SO_REUSEADDR
socket option for new connections.
The default setting is true
and may be configured using the
org.forgerock.opendj.transport.reuseAddress
property.
public static final Option<Integer> SO_LINGER_IN_SECONDS
SO_LINGER
socket option for new connections.
The default setting is -1
(disabled) and may be configured using
the org.forgerock.opendj.transport.linger
property.
public static final Option<Boolean> SO_KEEPALIVE
SO_KEEPALIVE
socket option for new connections.
The default setting is true
and may be configured using the
org.forgerock.opendj.transport.keepAlive
property.
public static final Option<DecodeOptions> DECODE_OPTIONS
public static final Option<SslOptions> SSL_OPTIONS
null
if SSL is disabled.public static final Option<IntConsumer> PROBE_BYTES_READ
public static final Option<IntConsumer> PROBE_BYTES_WRITTEN
public LdapConnectionFactory(String host, int port)
host
- The host name.port
- The port number.NullPointerException
- If host
was null
.public LdapConnectionFactory(String host, int port, Options options)
host
- The host name.port
- The port number.options
- The LDAP options to use when creating connections.NullPointerException
- If host
or options
was null
.public LdapConnectionFactory(LdapClient ldapClient)
ldapClient
- The LDAP client used to connect to the Directory Server.NullPointerException
- If ldapClient
or options
was null
.public Promise<Connection,LdapException> getConnectionAsync()
ConnectionFactory
Promise
can be used to
retrieve the completed connection.getConnectionAsync
in interface ConnectionFactory
public Connection getConnection() throws LdapException
ConnectionFactory
If the calling thread is interrupted while waiting for the connection
attempt to complete then the calling thread unblock and throw a
CancelledResultException
whose cause is the underlying
InterruptedException
.
getConnection
in interface ConnectionFactory
LdapException
- If the connection request failed for some reason.public void close()
ConnectionFactory
close
on a connection factory which is already closed has
no effect.
Applications should avoid closing connection factories while there are remaining active connections in use or connection attempts in progress.
close
in interface Closeable
close
in interface AutoCloseable
close
in interface ConnectionFactory
Connections.uncloseable(ConnectionFactory)
Copyright 2010-2022 ForgeRock AS.