Package org.forgerock.opendj.ldap

Class 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 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 AutoCloseable
        Specified by:
        close in interface Closeable
        Specified by:
        close in interface ConnectionFactory
        See Also:
        Connections.uncloseable(ConnectionFactory)