org.forgerock.opendj.ldap

Class LdapConnectionFactory

java.lang.Object

org.forgerock.opendj.ldap.LdapConnectionFactory

All Implemented Interfaces:

Closeable, AutoCloseable, ConnectionFactory

public final class LdapConnectionFactory
extends Object
implements ConnectionFactory

A factory class which can be used to obtain connections to an LDAP Directory Server. A connection attempt comprises of the following steps:

• first of all a TCP connection to the remote LDAP server is obtained. The attempt will fail if a connection is not obtained within the configured connect timeout
• if LDAPS (not StartTLS) is requested then an SSL handshake is performed. LDAPS is enabled by specifying the SSL_OPTIONS option along with SSL_USE_STARTTLS set to false
• if StartTLS is requested then a StartTLS request is sent and then an SSL handshake performed once the response has been received. StartTLS is enabled by specifying the SSL_OPTIONS option along with SSL_USE_STARTTLS set to true
• an initial authentication request is sent if the AUTHN_BIND_REQUEST option is specified
• if heart-beat support is enabled via the 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.
• the connect attempt will fail if it does not complete within the configured connection timeout. If the SSL handshake, StartTLS request, initial bind request, or initial heart-beat fail for any reason then the connection attempt will be deemed to have failed and an appropriate error returned.

Once a connection has been established heart-beats will be sent periodically on the connection based on the configured heart-beat interval. If the heart-beat times out then the server is assumed to be down and an appropriate ConnectionException generated and published to any registered ConnectionEventListeners. 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.

Field Summary

Fields

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 Summary

Constructors

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.

Method Summary

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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AUTHN_BIND_REQUEST

public static final Option<BindRequest> AUTHN_BIND_REQUEST

Configures the connection factory to return pre-authenticated connections using the specified 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.

AUTHN_BIND_REQUEST_FACTORY

public static final Option<Supplier<BindRequest>> AUTHN_BIND_REQUEST_FACTORY

Configures the connection factory to return pre-authenticated connections using 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.

CONNECT_TIMEOUT

public static final Option<Duration> CONNECT_TIMEOUT

Specifies the connect timeout spcified. If a connection is not established within the timeout period (incl. SSL negotiation, initial bind request, and/or heart-beat), then a 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.

HEARTBEAT_ENABLED

public static final Option<Boolean> HEARTBEAT_ENABLED

Configures the connection factory to periodically send "heart-beat" or "keep-alive" requests to the Directory Server. This feature allows client applications to proactively detect network problems or unresponsive servers. In addition, frequent heartbeat requests may also prevent load-balancers or Directory Servers from closing otherwise idle connections.

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

HEARTBEAT_INTERVAL

public static final Option<Duration> HEARTBEAT_INTERVAL

Specifies the time between successive heart-beat requests (default interval is 10 seconds). Heart-beats will only be sent if HEARTBEAT_ENABLED is set to true.

See Also:

HEARTBEAT_ENABLED

HEARTBEAT_SCHEDULER

public static final Option<ScheduledExecutorService> HEARTBEAT_SCHEDULER

Specifies the scheduler which will be used for periodically sending heart-beat requests. A system-wide scheduler will be used by default. Heart-beats will only be sent if HEARTBEAT_ENABLED is set to true.

See Also:

HEARTBEAT_ENABLED

HEARTBEAT_TIMEOUT

public static final 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). Heart-beats will only be sent if 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.

See Also:

HEARTBEAT_ENABLED

REQUEST_TIMEOUT

public static final Option<Duration> REQUEST_TIMEOUT

Specifies the operation timeout. If a response is not received from the Directory Server within the timeout period, then the operation will be abandoned and a 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.

SSL_USE_STARTTLS

public static final Option<Boolean> SSL_USE_STARTTLS

Specifies whether SSL or StartTLS should be used for securing connections when an SSL context is specified.

By default SSL will be used in preference to StartTLS.

HEARTBEAT_SEARCH_REQUEST

public static final Option<SearchRequest> HEARTBEAT_SEARCH_REQUEST

Specifies the parameters of the search request that will be used for heart-beats. The default heart-beat search request is a base object search against the root DSE requesting no attributes. Heart-beats will only be sent if HEARTBEAT_ENABLED is set to true.

See Also:

HEARTBEAT_ENABLED

TRANSPORT_PROVIDER_CLASS_LOADER

public static final Option<ClassLoader> TRANSPORT_PROVIDER_CLASS_LOADER

Specifies the class loader which will be used to load the 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.

TRANSPORT_PROVIDER

public static final Option<String> TRANSPORT_PROVIDER

Specifies the name of the provider to use for transport.

Transport providers implement TransportProvider interface.

The name should correspond to the name of an existing provider, as returned by TransportProvider#getName() method.

TCP_NO_DELAY

public static final Option<Boolean> TCP_NO_DELAY

Specifies the value of the TCP_NODELAY socket option for new connections.

The default setting is true and may be configured using the org.forgerock.opendj.transport.tcpNoDelay property.

SO_REUSE_ADDRESS

public static final Option<Boolean> SO_REUSE_ADDRESS

Specifies the value of the SO_REUSEADDR socket option for new connections.

The default setting is true and may be configured using the org.forgerock.opendj.transport.reuseAddress property.

SO_LINGER_IN_SECONDS

public static final Option<Integer> SO_LINGER_IN_SECONDS

Specifies the value of the 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.

SO_KEEPALIVE

public static final Option<Boolean> SO_KEEPALIVE

Specifies the value of the SO_KEEPALIVE socket option for new connections.

The default setting is true and may be configured using the org.forgerock.opendj.transport.keepAlive property.

DECODE_OPTIONS

public static final Option<DecodeOptions> DECODE_OPTIONS

Sets the decoding options which will be used to control how requests and responses are decoded.

SSL_OPTIONS

public static final Option<SslOptions> SSL_OPTIONS

Specifies the options to use for the SSL support or null if SSL is disabled.

PROBE_BYTES_READ

public static final Option<IntConsumer> PROBE_BYTES_READ

Callback invoked each time this server read bytes from the network. Must be thread-safe.

PROBE_BYTES_WRITTEN

public static final Option<IntConsumer> PROBE_BYTES_WRITTEN

Callback invoked each time this server write bytes to the network. Must be thread-safe.

Constructor Detail

LdapConnectionFactory

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

Parameters:

host - The host name.

port - The port number.

Throws:

NullPointerException - If host was null.

LdapConnectionFactory

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

Parameters:

host - The host name.

port - The port number.

options - The LDAP options to use when creating connections.

Throws:

NullPointerException - If host or options was null.

LdapConnectionFactory

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

Parameters:

ldapClient - The LDAP client used to connect to the Directory Server.

Throws:

NullPointerException - If ldapClient or options was null.

Method Detail

getConnectionAsync

public Promise<Connection,LdapException> getConnectionAsync()

Description copied from interface: ConnectionFactory

Asynchronously obtains a connection to the Directory Server associated with this connection factory. The returned Promise can be used to retrieve the completed connection.

Specified by:

getConnectionAsync in interface ConnectionFactory

Returns:

A promise which can be used to retrieve the connection.

getConnection

public Connection getConnection()
                         throws LdapException

Description copied from interface: ConnectionFactory

Returns a connection to the Directory Server associated with this connection factory. The connection returned by this method can be used immediately.

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.

Specified by:

getConnection in interface ConnectionFactory

Returns:

A connection to the Directory Server associated with this connection factory.

Throws:

LdapException - If the connection request failed for some reason.

close

public void close()

Description copied from interface: ConnectionFactory

Releases any resources associated with this connection factory. Depending on the implementation a factory may:

• do nothing
• close underlying connection factories (e.g. load-balancers)
• close pooled connections (e.g. connection pools)
• shutdown IO event service and related thread pools (e.g. Grizzly).

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

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Specified by:

close in interface ConnectionFactory

See Also:

Connections.uncloseable(ConnectionFactory)