Package 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
  • 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 Details

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

    • MEMORY_RX_TRANSPORT

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

    • ASYNC_RX_TRANSPORT

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

    • SYNC_RX_TRANSPORT

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

    • TRANSPORT

      public static final Option<String> TRANSPORT
      Specifies the name of the transport implementation to be used. Possible values are:

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

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

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

    • toString

      public String toString()
      Overrides:
      toString in class Object