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
    • the connect attempt will fail if it does not complete within the configured connection timeout. If the SSL handshake, StartTLS request, initial bind request 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 keep-alives will be sent periodically on the connection based on the configured keep-alive interval. If the keep-alive times out then the server is assumed to be down and an appropriate ConnectionException generated and published to any registered ConnectionEventListeners. Note however, that keep-alives will only be sent when the connection is determined to be reasonably idle: there is no point in sending keep-alives 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 keep-alive 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 keep-alives with bind or startTLS requests, ensuring that they are not performed concurrently. Specifically, bind and startTLS requests are queued up while a keep-alive is pending, and keep-alives 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.

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

      • DEFAULT_TRANSPORT

        public static final String DEFAULT_TRANSPORT
        The name of the default transport implementation which has the value "Default".
        See Also:
        Constant Field Values

      • MEMORY_RX_TRANSPORT

        public static final String MEMORY_RX_TRANSPORT
        The name of the memory transport implementation which has the value "MemoryRx".
        See Also:
        Constant Field Values

      • ASYNC_RX_TRANSPORT

        public static final String ASYNC_RX_TRANSPORT
        The name of asynchronous transport implementation which has the value "AsyncRx".
        See Also:
        Constant Field Values

      • SYNC_RX_TRANSPORT

        public static final String SYNC_RX_TRANSPORT
        The name of synchronous transport implementation which has the value "SyncRx".
        See Also:
        Constant Field Values

      • 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.io.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.io.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.io.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.io.keepAlive" property.

      • WRITE_TIMEOUT

        public static final Option<Duration> WRITE_TIMEOUT
        Maximum time allowed for write operations to complete. Once the timeout is reached the socket will become unusable and an appropriate exception returned.

      • BUFFER_SIZE

        public static final Option<Integer> BUFFER_SIZE
        Size of the buffer used when reading/writing data from/to the network.

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

      • MAX_MSG_SIZE_IN_BYTES

        public static final Option<Integer> MAX_MSG_SIZE_IN_BYTES
        Specifies the maximum request size in bytes for incoming LDAP messages. If an incoming request exceeds the limit then the connection will be aborted. Default value is 0, indicating that no limit will be enforced by default.

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

      • SELECTOR_THREAD_COUNT

        public static final Option<Integer> SELECTOR_THREAD_COUNT
        Specifies the number of threads which will be used to handle incoming network events. Default value is 0, indicating that the selected transport should select a suitable value.

      • SELECTOR_THREAD_NAME

        public static final Option<String> SELECTOR_THREAD_NAME
        Specifies the thread name used for selector threads.

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