Package org.forgerock.opendj.ldap

Class LDAPConnectionFactory

java.lang.Object
org.forgerock.opendj.ldap.CommonLDAPOptions
org.forgerock.opendj.ldap.LDAPConnectionFactory
All Implemented Interfaces:
Closeable, AutoCloseable, ConnectionFactory
public final class LDAPConnectionFactory extends CommonLDAPOptions 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_CONTEXT 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_CONTEXT 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
    Description
    static final org.forgerock.util.Option<BindRequest>
    AUTHN_BIND_REQUEST
    Configures the connection factory to return pre-authenticated connections using the specified BindRequest.
    static final org.forgerock.util.Option<org.forgerock.util.time.Duration>
    CONNECT_TIMEOUT
    Specifies the connect timeout spcified.
    static final org.forgerock.util.Option<Boolean>
    HEARTBEAT_ENABLED
    Configures the connection factory to periodically send "heart-beat" or "keep-alive" requests to the Directory Server.
    static final org.forgerock.util.Option<org.forgerock.util.time.Duration>
    HEARTBEAT_INTERVAL
    Specifies the time between successive heart-beat requests (default interval is 10 seconds).
    static final org.forgerock.util.Option<ScheduledExecutorService>
    HEARTBEAT_SCHEDULER
    Specifies the scheduler which will be used for periodically sending heart-beat requests.
    static final org.forgerock.util.Option<SearchRequest>
    HEARTBEAT_SEARCH_REQUEST
    Specifies the parameters of the search request that will be used for heart-beats.
    static final org.forgerock.util.Option<org.forgerock.util.time.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 final org.forgerock.util.Option<org.forgerock.util.time.Duration>
    REQUEST_TIMEOUT
    Specifies the operation timeout.
    static final org.forgerock.util.Option<SSLContext>
    SSL_CONTEXT
    Specifies the SSL context which will be used when initiating connections with the Directory Server.
    static final org.forgerock.util.Option<List<String>>
    SSL_ENABLED_CIPHER_SUITES
    Specifies the cipher suites enabled for secure connections with the Directory Server.
    static final org.forgerock.util.Option<List<String>>
    SSL_ENABLED_PROTOCOLS
    Specifies the protocol versions enabled for secure connections with the Directory Server.
    static final org.forgerock.util.Option<Boolean>
    SSL_USE_STARTTLS
    Specifies whether SSL or StartTLS should be used for securing connections when an SSL context is specified.

    Fields inherited from class org.forgerock.opendj.ldap.CommonLDAPOptions

    LDAP_DECODE_OPTIONS, SO_KEEPALIVE, SO_LINGER_IN_SECONDS, SO_REUSE_ADDRESS, TCP_NO_DELAY, TRANSPORT_PROVIDER, TRANSPORT_PROVIDER_CLASS_LOADER

  • Constructor Summary

    Constructors
    Constructor
    Description
    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, org.forgerock.util.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
    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.
    org.forgerock.util.promise.Promise<Connection,LdapException>
    getConnectionAsync()
    Asynchronously obtains a connection to the Directory Server associated with this connection factory.
    String
    getHostName()
    Returns the host name of the Directory Server.
    int
    getPort()
    Returns the port of the Directory Server.
    String
    getProviderName()
    Returns the name of the transport provider, which provides the implementation of this factory.
    String
    toString()
     

    Methods inherited from class java.lang.Object

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

  • Field Details

    • AUTHN_BIND_REQUEST

      public static final org.forgerock.util.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.

    • CONNECT_TIMEOUT

      public static final org.forgerock.util.Option<org.forgerock.util.time.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 org.forgerock.util.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 org.forgerock.util.Option<org.forgerock.util.time.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_SCHEDULER

      public static final org.forgerock.util.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_TIMEOUT

      public static final org.forgerock.util.Option<org.forgerock.util.time.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:

    • REQUEST_TIMEOUT

      public static final org.forgerock.util.Option<org.forgerock.util.time.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_CONTEXT

      public static final org.forgerock.util.Option<SSLContext> SSL_CONTEXT
      Specifies the SSL context which will be used when initiating connections with the Directory Server.

      By default no SSL context will be used, indicating that connections will not be secured. If an SSL context is set then connections will be secured using either SSL or StartTLS depending on SSL_USE_STARTTLS.

    • SSL_ENABLED_CIPHER_SUITES

      public static final org.forgerock.util.Option<List<String>> SSL_ENABLED_CIPHER_SUITES
      Specifies the cipher suites enabled for secure connections with the Directory Server.

      The suites must be supported by the SSLContext specified by option SSL_CONTEXT. Only the suites listed in the parameter are enabled for use.

    • SSL_ENABLED_PROTOCOLS

      public static final org.forgerock.util.Option<List<String>> SSL_ENABLED_PROTOCOLS
      Specifies the protocol versions enabled for secure connections with the Directory Server.

      The protocols must be supported by the SSLContext specified by option SSL_CONTEXT. Only the protocols listed in the parameter are enabled for use.

    • SSL_USE_STARTTLS

      public static final org.forgerock.util.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 org.forgerock.util.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:

  • Constructor Details

    • 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.
      ProviderNotFoundException - if no provider is available or if the provider requested using options is not found.

    • LDAPConnectionFactory

      public LDAPConnectionFactory(String host, int port, org.forgerock.util.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.
      ProviderNotFoundException - if no provider is available or if the provider requested using options is not found.

  • Method Details

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

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

    • getConnectionAsync

      public org.forgerock.util.promise.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.

    • getHostName

      public String getHostName()
      Returns the host name of the Directory Server. The returned host name is the same host name that was provided during construction and may be an IP address. More specifically, this method will not perform a reverse DNS lookup.
      Returns:
      The host name of the Directory Server.

    • getPort

      public int getPort()
      Returns the port of the Directory Server.
      Returns:
      The port of the Directory Server.

    • getProviderName

      public String getProviderName()
      Returns the name of the transport provider, which provides the implementation of this factory.
      Returns:
      The name of actual transport provider.

    • toString

      public String toString()
      Overrides:
      toString in class Object