Package org.forgerock.opendj.ldap

Class LdapClients

java.lang.Object
org.forgerock.opendj.ldap.LdapClients
public final class LdapClients extends Object
This class contains methods for creating and manipulating LDAP clients and connections.

  • Field Details

    • LOAD_BALANCER_AVAILABILITY_CHECK_INTERVAL

      public static final Option<Duration> LOAD_BALANCER_AVAILABILITY_CHECK_INTERVAL
      Specifies the time between successive availability check requests (default interval is 5 seconds).

      The default availability check interval is set to 5 seconds and may be configured using the "org.forgerock.opendj.io.availabilityCheckInterval" property.

    • LOAD_BALANCER_AVAILABILITY_CHECK_TIMEOUT

      public static final Option<Duration> LOAD_BALANCER_AVAILABILITY_CHECK_TIMEOUT
      Specifies the timeout for availability checks, after which the remote Directory Server will be deemed to be unavailable (default timeout is 3 seconds). If a LDAP_CLIENT_REQUEST_TIMEOUT request timeout is also set then the lower of the two will be used for sending requests.

      The default availability check timeout is set to 3 seconds and may be configured using the "org.forgerock.opendj.io.availabilityCheckTimeout" property.

    • LOAD_BALANCER_AVAILABILITY_CHECK_SEARCH_REQUEST

      public static final Option<SearchRequest> LOAD_BALANCER_AVAILABILITY_CHECK_SEARCH_REQUEST
      Specifies the parameters of the search request that will be used for availability check.

      The default search base DN is the rootDSE ("") and it can be configured by using the "org.forgerock.opendj.io.availabilityCheckSearchBaseDn" property. The default search filter is the absolute true filter ( '(&)' ) and it can be configured by using the "org.forgerock.opendj.io.availabilityCheckSearchFilter" property.

    • LOAD_BALANCER_EVENT_LISTENER

      public static final Option<LoadBalancerEventListener> LOAD_BALANCER_EVENT_LISTENER
      Specifies the event listener which should be notified whenever a load-balanced LDAP client changes state from online to offline or vice-versa. By default events will be logged to the LoadBalancingAlgorithm logger using the LoadBalancerEventListener.LOG_EVENTS listener.

    • CONNECTION_POOL_EVENT_LISTENER

      public static final Option<ConnectionPoolEventListener> CONNECTION_POOL_EVENT_LISTENER
      Specifies the event listener which should be notified whenever an event occurs in a connection pool.

    • LOAD_BALANCER_SCHEDULER

      public static final Option<ScheduledExecutorService> LOAD_BALANCER_SCHEDULER
      Specifies the scheduler which will be used for periodically reconnecting to offline LDAP clients. A system-wide scheduler will be used by default.

    • LOAD_BALANCER_IDLE_SERVER_SELECTOR

      @Deprecated public static final Option<IntUnaryOperator> LOAD_BALANCER_IDLE_SERVER_SELECTOR
      Deprecated.
      For internal use only. This option will be removed in future version and will not be replaced.
      Specifies a function to choose a server when all servers are idle.

    • LOAD_BALANCER_PARTITION_BASE_DNS

      public static final Option<Set<Dn>> LOAD_BALANCER_PARTITION_BASE_DNS
      Specifies partition base DNs. Entries immediately subordinate to the base DNs will be considered to be the root of a sub-tree whose entries belong to the same partition. For example, a partition base DN of "ou=people,dc=example,dc=com" would mean that "uid=bjensen,ou=people,dc=example,dc=com" and "deviceid=12345,uid=bjensen,ou=people,dc=example,dc=com" both belong to the same partition.

    • LOAD_BALANCER_BASE_DNS

      public static final Option<Collection<Dn>> LOAD_BALANCER_BASE_DNS
      Specifies the base DN(s) for the data that the ldap service handles.

      Leave empty if you want the ldap service to handle all the base DNs it can find in the backend servers.

    • CONNECTION_POOL_MIN_SIZE

      public static final Option<Integer> CONNECTION_POOL_MIN_SIZE
      The minimum size for the connection pool. By default the minimum size is 0, meaning that no connections will remain open when the connection pool is idle.

    • CONNECTION_POOL_MAX_SIZE

      public static final Option<Integer> CONNECTION_POOL_MAX_SIZE
      The maximum size for the connection pool. By default connection pools are unbounded (Integer.MAX_VALUE), meaning that new connections will be created whenever there are no idle connections available. This is because many client applications perform blocking I/O and must be able to acquire connections when performing nested operations, otherwise they are at risk of deadlock. Set this to a lower number in non-blocking applications.

    • CONNECTION_POOL_IDLE_TIMEOUT

      public static final Option<Duration> CONNECTION_POOL_IDLE_TIMEOUT
      The time interval after which idle connections can be closed, shrinking the connection pool towards the minimum size.

    • CONNECTION_POOL_SCHEDULER

      public static final Option<ScheduledExecutorService> CONNECTION_POOL_SCHEDULER
      Specifies the scheduler which will be used for periodically checking idle connections and timed-out connection attempts. A system-wide scheduler will be used by default.

    • LDAP_CLIENT_REQUEST_TIMEOUT

      public static final Option<Duration> LDAP_CLIENT_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.

    • LDAP_CLIENT_ENABLE_PRE_AUTHENTICATION

      public static final Option<Boolean> LDAP_CLIENT_ENABLE_PRE_AUTHENTICATION
      Configures whether the connection factory must return pre-authenticated connections. If true, connections returned will be pre-authenticated using the BindRequest specified in LDAP_CLIENT_AUTHN_BIND_REQUEST, or the bind request factory specified in LDAP_CLIENT_AUTHN_BIND_REQUEST_FACTORY. Note that in this case, the connection factory will support all operations with the exception of Bind requests. Attempts to perform a Bind will result in an UnsupportedOperationException.
      See Also:

    • LDAP_CLIENT_AUTHN_BIND_REQUEST

      public static final Option<BindRequest> LDAP_CLIENT_AUTHN_BIND_REQUEST
      Configures the BindRequest used for pre-authenticated connection or availability check made by load-balancers.

      If the Bind request fails for some reason (e.g. invalid credentials), then the connection attempt will fail and an LdapException will be thrown.

      See Also:

    • LDAP_CLIENT_AUTHN_BIND_REQUEST_FACTORY

      public static final Option<Supplier<BindRequest>> LDAP_CLIENT_AUTHN_BIND_REQUEST_FACTORY
      Configures the BindRequest supplier used for pre-authenticated connection or availability checks made by load-balancers

      If the Bind request fails for some reason (e.g. invalid credentials), then the connection attempt will fail and an LdapException will be thrown.

      See Also:

    • LDAP_CLIENT_KEEP_ALIVE_ENABLED

      public static final Option<Boolean> LDAP_CLIENT_KEEP_ALIVE_ENABLED
      Configures the connection factory to periodically send keep-alives to the Directory Server. This feature allows client applications to proactively detect network problems or unresponsive servers. In addition, frequent keep-alives may also prevent load-balancers or Directory Servers from closing otherwise idle connections.

      Once a connection has been established successfully, the connection factory will periodically send keep-alives on the connection based on the configured keep-alive interval. If the Directory Server is too slow to respond to the keep-alive 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. The LDAP connection 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.

      By default the keep-alive is enabled and may be disabled using the "org.forgerock.opendj.io.keepAliveEnabled" property.

    • LDAP_CLIENT_KEEP_ALIVE_INTERVAL

      public static final Option<Duration> LDAP_CLIENT_KEEP_ALIVE_INTERVAL
      Specifies the time between successive keep-alives (default interval is 300 seconds). Keep-alives will only be sent if LDAP_CLIENT_KEEP_ALIVE_ENABLED is set to true.

      The default keep-alive interval is set to 5 minutes and may be configured using the "org.forgerock.opendj.io.keepAliveInterval" property.

      See Also:

    • LDAP_CLIENT_KEEP_ALIVE_SCHEDULER

      public static final Option<ScheduledExecutorService> LDAP_CLIENT_KEEP_ALIVE_SCHEDULER
      Specifies the scheduler which will be used for periodically sending keep-alives. A system-wide scheduler will be used by default. Keep-alives will only be sent if LDAP_CLIENT_KEEP_ALIVE_ENABLED is set to true.
      See Also:

    • LDAP_CLIENT_KEEP_ALIVE_TIMEOUT

      public static final Option<Duration> LDAP_CLIENT_KEEP_ALIVE_TIMEOUT
      Specifies the timeout for keep-alives, after which the remote Directory Server will be deemed to be disconnected (default timeout is 3 seconds). Keep-alives will only be sent if LDAP_CLIENT_KEEP_ALIVE_ENABLED is set to true. If a request timeout is also set then the lower of the two will be used for sending keep-alives.

      The default keep-alive timeout is set to 3 seconds and may be configured using the "org.forgerock.opendj.io.keepAliveTimeout" property.

      See Also:

    • LDAP_CLIENT_SSL_USE_STARTTLS

      public static final Option<Boolean> LDAP_CLIENT_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.

    • LDAP_CLIENT_KEEP_ALIVE_SEARCH_REQUEST

      public static final Option<SearchRequest> LDAP_CLIENT_KEEP_ALIVE_SEARCH_REQUEST
      Specifies the parameters of the search request that will be used for keep-alives. The default keep-alive search request is a base object search against the root DSE requesting no attributes. Keep-alives will only be sent if LDAP_CLIENT_KEEP_ALIVE_ENABLED is set to true.
      See Also:

    • PROXY_PROTOCOL_HEADER_CLIENT

      public static final Option<ProxyProtocolHeader> PROXY_PROTOCOL_HEADER_CLIENT
      Enables the proxy protocol for client connections using the provided proxy header.

    • CONNECT_TIMEOUT

      public static final Option<Duration> CONNECT_TIMEOUT
      Specifies the connect timeout. If a connection is not established within the timeout period (incl. SSL negotiation, initial bind request, keep-alive, availability check), 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.

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

  • Method Details

    • newLdapClient

      public static LdapClient newLdapClient(String host, int port)
      Creates a new LDAP client which can be used to create LDAP connections to the Directory Server at the provided host and port number, and using default options.
      Parameters:
      host - The host name.
      port - The port number.
      Returns:
      The new LDAP client which will connect to the specified directory server.
      Throws:
      NullPointerException - If host was null.
      UnknownRxTransportException - if no provider is available or if the provider requested using options is not found.
      See Also:

    • newLdapClient

      public static LdapClient newLdapClient(String host, int port, Options options)
      Creates a new LDAP client which can be used to create LDAP connections to the Directory Server at the provided host and port number and custom options.
      Parameters:
      host - The host name.
      port - The port number.
      options - The LDAP options to use when creating connections.
      Returns:
      The new LDAP client which will connect to the specified directory server.
      Throws:
      NullPointerException - If host or options was null.
      UnknownRxTransportException - if no provider is available or if the provider requested using options is not found.
      See Also:

    • newAffinityRequestLoadBalancer

      public static LdapClient newAffinityRequestLoadBalancer(Map<com.forgerock.opendj.util.HostPort,? extends LdapClient> clients, Options options)
      Creates a new "affinity" load-balancer which will load-balance individual requests across the provided set of LDAP clients, each typically representing a single replica, using an algorithm that ensures that requests targeting a given DN will always be routed to the same replica. In other words, this load-balancer increases consistency whilst maintaining read-scalability by simulating a "single master" replication topology, where each replica is responsible for a subset of the entries. When a replica is unavailable the load-balancer "fails over" by performing a linear probe in order to find the next available replica thus ensuring high-availability when a network partition occurs while sacrificing consistency, since the unavailable replica may still be visible to other clients.

      This load-balancer distributes requests based on the hash of their target DN and handles all core operations, as well as any password modify extended requests and SASL bind requests which use authentication IDs having the "dn:" form. Note that subtree operations (searches, subtree deletes, and modify DN) are likely to include entries which are "mastered" on different replicas, so client applications should be more tolerant of inconsistencies. Requests that are either unrecognized or that do not have a parameter that may be considered to be a target DN will be routed randomly.

      NOTE: this LDAP client returns fake connections, since real connections are obtained for each request. Therefore, the returned fake connections have certain limitations: abandon requests will be ignored since they cannot be routed; connection event listeners can be registered, but will only be notified when the fake connection is closed or when all of the LDAP clients are unavailable.

      NOTE: in deployments where there are multiple client applications, care should be taken to ensure that the clients are configured using the same ordering, otherwise requests will not be routed consistently across the client applications.

      The implementation periodically attempts to connect using failed LDAP clients in order to determine if they have become available again.

      Parameters:
      clients - The LDAP clients.
      options - This configuration options for the load-balancer.
      Returns:
      The new affinity load balancer.
      See Also:

    • newCachedConnectionPool

      public static ConnectionPool newCachedConnectionPool(LdapClient client)
      Creates a new connection pool which creates new connections as needed using the provided LDAP client, but will reuse previously allocated connections when they are available.

      Connections which have not been used for sixty seconds are closed and removed from the pool. Thus, a pool that remains idle for long enough will not contain any cached connections.

      Connections obtained from the connection pool are guaranteed to be valid immediately before being returned to the calling application. More specifically, connections which have remained idle in the connection pool for a long time and which have been remotely closed due to a time out will never be returned. However, once a pooled connection has been obtained it is the responsibility of the calling application to handle subsequent connection failures, these being signaled via a ConnectionException.

      Parameters:
      client - The LDAP client to use for creating new connections.
      Returns:
      The new connection pool.
      Throws:
      NullPointerException - If client was null.

    • newCachedConnectionPool

      public static ConnectionPool newCachedConnectionPool(LdapClient client, int corePoolSize, int maximumPoolSize, long idleTimeout, TimeUnit unit)
      Creates a new connection pool which creates new connections as needed using the provided LDAP client, but will reuse previously allocated connections when they are available.

      Attempts to use more than maximumPoolSize connections at once will block until a connection is released back to the pool. In other words, this pool will prevent applications from using more than maximumPoolSize connections at the same time.

      Connections which have not been used for the provided idleTimeout period are closed and removed from the pool, until there are only corePoolSize connections remaining.

      Connections obtained from the connection pool are guaranteed to be valid immediately before being returned to the calling application. More specifically, connections which have remained idle in the connection pool for a long time and which have been remotely closed due to a time out will never be returned. However, once a pooled connection has been obtained it is the responsibility of the calling application to handle subsequent connection failures, these being signaled via a ConnectionException.

      Parameters:
      client - The LDAP client to use for creating new connections.
      corePoolSize - The minimum number of connections to keep in the pool, even if they are idle.
      maximumPoolSize - The maximum number of connections to allow in the pool.
      idleTimeout - The time out period, after which unused non-core connections will be closed.
      unit - The time unit for the keepAliveTime argument.
      Returns:
      The new connection pool.
      Throws:
      IllegalArgumentException - If corePoolSize, maximumPoolSize are less than or equal to zero, or if idleTimeout is negative, or if corePoolSize is greater than maximumPoolSize, or if idleTimeout is non-zero and unit is null.
      NullPointerException - If client was null.

    • newCachedConnectionPool

      public static ConnectionPool newCachedConnectionPool(LdapClient client, int corePoolSize, int maximumPoolSize, long idleTimeout, TimeUnit unit, ScheduledExecutorService scheduler)
      Creates a new connection pool which creates new connections as needed using the provided LDAP client, but will reuse previously allocated connections when they are available.

      Attempts to use more than maximumPoolSize connections at once will block until a connection is released back to the pool. In other words, this pool will prevent applications from using more than maximumPoolSize connections at the same time.

      Connections which have not been used for the provided idleTimeout period are closed and removed from the pool, until there are only corePoolSize connections remaining.

      Connections obtained from the connection pool are guaranteed to be valid immediately before being returned to the calling application. More specifically, connections which have remained idle in the connection pool for a long time and which have been remotely closed due to a time out will never be returned. However, once a pooled connection has been obtained it is the responsibility of the calling application to handle subsequent connection failures, these being signaled via a ConnectionException.

      Parameters:
      client - The LDAP client to use for creating new connections.
      corePoolSize - The minimum number of connections to keep in the pool, even if they are idle.
      maximumPoolSize - The maximum number of connections to allow in the pool.
      idleTimeout - The time out period, after which unused non-core connections will be closed.
      unit - The time unit for the keepAliveTime argument.
      scheduler - The scheduler which should be used for periodically checking for idle connections, or null if the default scheduler should be used.
      Returns:
      The new connection pool.
      Throws:
      IllegalArgumentException - If corePoolSize, maximumPoolSize are less than or equal to zero, or if idleTimeout is negative, or if corePoolSize is greater than maximumPoolSize, or if idleTimeout is non-zero and unit is null.
      NullPointerException - If client was null.

    • newCachedConnectionPool

      public static ConnectionPool newCachedConnectionPool(LdapClient client, Options options)
      Creates a new connection pool which creates new connections as needed using the provided LDAP client, but will reuse previously allocated connections when they are available.

      Attempts to use more than CONNECTION_POOL_MAX_SIZE connections at once will block until a connection is released back to the pool. In other words, this pool will prevent applications from using more than CONNECTION_POOL_MAX_SIZE connections at the same time.

      Connections which have not been used for the provided CONNECTION_POOL_IDLE_TIMEOUT period are closed and removed from the pool, until there are only CONNECTION_POOL_MIN_SIZE connections remaining.

      Connections obtained from the connection pool are guaranteed to be valid immediately before being returned to the calling application. More specifically, connections which have remained idle in the connection pool for a long time and which have been remotely closed due to a time out will never be returned. However, once a pooled connection has been obtained it is the responsibility of the calling application to handle subsequent connection failures, these being signaled via a ConnectionException.

      Parameters:
      client - The LDAP client to use for creating new connections.
      options - The configuration for the connection pool.
      Returns:
      The new connection pool.
      Throws:
      IllegalArgumentException - If CONNECTION_POOL_MIN_SIZE, CONNECTION_POOL_MAX_SIZE are less than or equal to zero, or if CONNECTION_POOL_IDLE_TIMEOUT is negative, or if CONNECTION_POOL_MIN_SIZE is greater than CONNECTION_POOL_MAX_SIZE.
      NullPointerException - If client was null.
      See Also:

    • newFailoverLoadBalancer

      public static LdapClient newFailoverLoadBalancer(Collection<? extends LdapClient> clients, Options options)
      Creates a new "fail-over" load-balancer which will load-balance connections across the provided set of LDAP clients. A fail-over load balancing algorithm provides fault tolerance across multiple underlying LDAP clients.

      This algorithm is typically used for load-balancing between data centers, where there is preference to always forward connection requests to the closest available data center. This algorithm contrasts with the newLeastRequestsLoadBalancer(Collection, Options) which is used for load-balancing within a data center.

      This algorithm selects LDAP clients based on the order in which they were provided during construction. More specifically, an attempt to obtain a LDAP client will always return the first operational LDAP client in the list. Applications should, therefore, organize the LDAP clients such that the preferred (usually the closest) LDAP clients appear before those which are less preferred.

      If a problem occurs that temporarily prevents connections from being obtained for one of the LDAP clients, then this algorithm automatically "fails over" to the next operational LDAP client in the list. If none of the LDAP clients are operational then a ConnectionException is returned to the client.

      The implementation periodically attempts to connect using failed LDAP clients in order to determine if they have become available again.

      Parameters:
      clients - The LDAP clients.
      options - This configuration options for the load-balancer.
      Returns:
      The new fail-over load balancer.
      See Also:

    • newFixedConnectionPool

      public static ConnectionPool newFixedConnectionPool(LdapClient client, int poolSize)
      Creates a new connection pool which will maintain poolSize connections created using the provided LDAP client.

      Attempts to use more than poolSize connections at once will block until a connection is released back to the pool. In other words, this pool will prevent applications from using more than poolSize connections at the same time.

      Connections obtained from the connection pool are guaranteed to be valid immediately before being returned to the calling application. More specifically, connections which have remained idle in the connection pool for a long time and which have been remotely closed due to a time out will never be returned. However, once a pooled connection has been obtained it is the responsibility of the calling application to handle subsequent connection failures, these being signaled via a ConnectionException.

      Parameters:
      client - The LDAP client to use for creating new connections.
      poolSize - The maximum size of the connection pool.
      Returns:
      The new connection pool.
      Throws:
      IllegalArgumentException - If poolSize is negative.
      NullPointerException - If client was null.

    • newFixedSizeDistributionLoadBalancer

      public static LdapClient newFixedSizeDistributionLoadBalancer(Set<Dn> partitionBaseDns, ConsistentHashMap<? extends LdapClient> partitions, Options options)
      Creates a distribution load balancer which uses consistent hashing to distributes requests across a set of partitions based on a hash of each request's target DN. More precisely, a partition is selected as follows:
      • if the targeted entry lies beneath a partition base DN then the partition is selected based on a hash of the DN which is superior to the target DN and immediately subordinate to the partition base DN
      • otherwise, if the request is not a search then the request is routed to a random partition
      • otherwise, if the search request targets a partition base DN, or a superior thereof, then the search is routed to a random partition or broadcast to all partitions, depending on the search scope. When broadcasting, care is taken to re-scope sub-requests in order to avoid returning duplicate entries
      • otherwise, the search is routed to a random partition because its scope lies outside of the partition space.
      This load balancer allows client applications to linearly scale their deployment for write throughput as well as total number of entries. For example, if a single replicated topology can support 10000 updates/s and a total of 100M entries, then a 4 way distributed topology could support up to 40000 updates/s and 400M entries.

      NOTE: there are a number of assumptions in the design of this load balancer as well as a number of limitations:

      • simple paged results, server side sorting, and VLV request controls are not supported for searches which traverse all partitions.
      • persistent searches which traverse all partitions are only supported if they request changes only.
      • requests which target an entry which is not below the partition base DN will be routed to a partition selected based on the request's DN, thereby providing affinity. Note that this behavior assumes that entries which are not below the partition base DN are replicated across all partitions.
      • searches that traverse multiple partitions as well as entries above the partition base DN may return results in a non-hierarchical order. Specifically, entries from a partition (below the partition base DN) may be returned before entries above the partition base DN. Although not required by the LDAP standard, some legacy clients expect entries to be returned in hierarchical order.
      Parameters:
      partitionBaseDns - The DNs beneath which data is partitioned. All other data is assumed to be shared across all partitions.
      partitions - The consistent hash map containing the partitions to be distributed.
      options - The configuration options for the load-balancer (no options are supported currently).
      Returns:
      The new distribution load balancer.

    • newInternalLdapClientSocket

      public static LdapClientSocket newInternalLdapClientSocket(BiFunction<Integer,Request,Flowable<Response>> requestHandler)
      Creates a new LdapClientSocket which will route requests to the provided requestHandler.

      When processing requests, requestHandler implementations are passed a pseudo request ID which is incremented for each successive internal request on a per client connection basis. The request ID may be useful for logging purposes.

      An internal connection does not require requestHandler implementations to return a result when processing requests. However, it is recommended that implementations do always return results even for abandoned requests. This is because application client threads may block indefinitely waiting for results.

      Parameters:
      requestHandler - The request handler which will be used for all client connections.
      Returns:
      The new internal client socket.
      Throws:
      NullPointerException - If requestHandler was null.

    • newInternalLdapClient

      public static LdapClient newInternalLdapClient(BiFunction<Integer,Request,Flowable<Response>> requestHandler)
      Creates a new LdapClient which will route requests to the provided requestHandler.

      When processing requests, requestHandler implementations are passed a pseudo request ID which is incremented for each successive internal request on a per client connection basis. The request ID may be useful for logging purposes.

      An internal connection does not require requestHandler implementations to return a result when processing requests. However, it is recommended that implementations do always return results even for abandoned requests. This is because application client threads may block indefinitely waiting for results.

      Parameters:
      requestHandler - The request handler which will be used for all client connections.
      Returns:
      The new internal client socket factory.
      Throws:
      NullPointerException - If requestHandler was null.

    • newLeastRequestsLoadBalancer

      public static LdapClient newLeastRequestsLoadBalancer(Collection<? extends LdapClient> clients, Options options)
      Creates a new "least requests" load-balancer which will load-balance individual requests across the provided set of LDAP clients, each typically representing a single replica, using an algorithm that ensures that requests are routed to the replica which has the minimum number of active requests.

      In other words, this load-balancer provides availability and partition tolerance, but sacrifices consistency. When a replica is not available, its number of active requests will not decrease until the requests time out, which will have the effect of directing requests to the other replicas. Consistency is low compared to the "affinity" load-balancer, because there is no guarantee that requests for the same DN are directed to the same replica.

      It is possible to increase consistency by providing a AffinityControl with a request. The control value will then be used to compute a hash that will determine the connection to use. In that case, the "least requests" behavior is completely overridden, i.e. the most saturated connection may be chosen depending on the hash value.

      NOTE: this LDAP client returns fake connections, since real connections are obtained for each request. Therefore, the returned fake connections have certain limitations: abandon requests will be ignored since they cannot be routed; connection event listeners can be registered, but will only be notified when the fake connection is closed or when all of the LDAP clients are unavailable.

      NOTE:Server selection is only based on information which is local to the client application. If other applications are accessing the same servers then their additional load is not taken into account. Therefore, this load balancer is only effective if all client applications access the servers in a similar way.

      The implementation periodically attempts to connect using failed LDAP clients in order to determine if they have become available again.

      Parameters:
      clients - The LDAP clients.
      options - This configuration options for the load-balancer.
      Returns:
      The new least requests load balancer.
      See Also:

    • newNamedLdapClient

      public static LdapClient newNamedLdapClient(LdapClient client, String name)
      Creates a new LDAP client which forwards connection requests to the provided client, but whose toString method will always return name.

      This method may be useful for debugging purposes in order to more easily identity LDAP clients.

      Parameters:
      client - The LDAP client to be named.
      name - The name of the LDAP client.
      Returns:
      The named LDAP client.
      Throws:
      NullPointerException - If client or name was null.

    • newNullLdapClient

      public static LdapClient newNullLdapClient()
      Returns an LDAP client which always throws ResultCode.CLIENT_SIDE_CONNECT_ERROR, without any error message.
      Returns:
      The LDAP client.

    • newNullLdapClient

      public static LdapClient newNullLdapClient(String name, LocalizableMessage connectErrorMessage)
      Returns an LDAP client which always throws ResultCode.CLIENT_SIDE_CONNECT_ERROR using the provided error message.
      Parameters:
      name - The name of the LDAP client.
      connectErrorMessage - The error message to use when returning ResultCode.CLIENT_SIDE_CONNECT_ERROR.
      Returns:
      The LDAP client.

    • uncloseable

      public static LdapClientSocket uncloseable(LdapClientSocket socket)
      Returns an uncloseable view of the provided socket. Attempts to call LdapClientSocket.close() or LdapClientSocket.close(UnbindRequest, String) will be ignored.
      Parameters:
      socket - The socket whose close methods are to be disabled.
      Returns:
      An uncloseable view of the provided socket.

    • newLdapService

      public static LdapClient newLdapService(Collection<String> bootstrapReplicationServerAdminEndpoints, Supplier<BindRequest> bindRequestSupplier, Options loadBalancingOptions, Options serviceDiscoveryOptions)
      Creates a new LDAP load-balancer able to discover all the replicas in a directory service, load balance across them all, and reconfigure itself according to changes affecting the availability of the replicas.

      This load balancer should be used for regular applications (AM, IDM, etc), where connections are pre-authenticated and operations performed by the application for the application.

      This load balancer uses the "bind upfront" authentication strategy: once connections are established to the discovered backend servers, a bind happens (using BindRequest supplied by bindRequestSupplier) only once after connection establishment. Any further bind attempts will be rejected.

      This load balancer is configured with the administration host and ports of one or several replication servers. These replication servers are queried to find information about all the replicas in the topology, and how to connect to them. Once discovered, the replicas are used as backend servers for this load balancer. This load balancer is able to react to changes in the backend servers: stops, start, new replica joining in, etc.

      This load balancer is built using a stack of LdapClient: 
      
 failover load balancer (over primary and secondary servers - returned by this method)
  +- affinity load balancers (one for primary servers, one for secondary servers)
      +- cached connection pool
          +- ldap client

      The usual options are supported for configuring the various load balancer stages. Please refer to the various methods creating LDAP clients for the options. Connection pools can be configured using the CONNECTION_POOL_MIN_SIZE, CONNECTION_POOL_MAX_SIZE and CONNECTION_POOL_IDLE_TIMEOUT options.

      Parameters:
      bootstrapReplicationServerAdminEndpoints - The admin host and ports of the bootstrap replication servers.
      bindRequestSupplier - Factory of bind requests used to authenticate for doing the load balancing.
      loadBalancingOptions - Configuration options for load-balancing.
      serviceDiscoveryOptions - Configuration options for the service discovery.
      Returns:
      The new load balancer, load balancing requests on the whole topology of directory services.
      See Also:

    • newProxyLdapService

      public static LdapClient newProxyLdapService(Collection<String> bootstrapReplicationServerAdminHostPorts, Options loadBalancingOptions, Options serviceDiscoveryOptions)
      Creates a new LDAP load-balancer able to discover all the replicas in a directory service, load balance across them all, and reconfigure itself according to changes affecting the availability of the replicas.

      This load balancer should be used for proxy applications, where operations are performed by the proxy on behalf of users.

      This load balancer uses the "bind at anytime" authentication strategy which allows bind requests to be issued at anytime. To support this, two connections pools are created for each discovered backend server: one for bind requests and another one for all the other types of request. Since binds are stateful (they change the state of the LDAP connection) and since multiple clients may require different identities, the binds are issued on a dedicated connection pool, and the authorization DN is assigned to a dedicated connection on bind success. The other types of requests are routed to the non-bind connection pool, and the identity is attached via a proxied auth V2 request control.

      This load balancer is configured with the administration host and ports of one or several replication servers. These replication servers are queried to find information about all the replicas in the topology, and how to connect to them. Once discovered, the replicas are used as backend servers for this load balancer. This load balancer is able to react to changes in the backend servers: stops, start, new replica joining in, etc.

      This load balancer is built using a stack of LdapClient: 
      
 failover load balancer (one for binds, one for other requests - over primary and secondary servers -
                         returned by this method)
  +- affinity load balancers (one for primary servers, one for secondary servers)
      +- cached connection pool (one for bind requests, one for non-bind requests)
          +- ldap client

      The usual options are supported for configuring the various load balancer stages. Please refer to the various methods creating LDAP clients for the options. Connection pools can be configured using the CONNECTION_POOL_MIN_SIZE, CONNECTION_POOL_MAX_SIZE and CONNECTION_POOL_IDLE_TIMEOUT options.

      Parameters:
      bootstrapReplicationServerAdminHostPorts - The admin host and ports of the bootstrap replication servers.
      loadBalancingOptions - Configuration options for load-balancing.
      serviceDiscoveryOptions - Configuration options for the service discovery.
      Returns:
      The new load balancer, load balancing requests on the whole topology of directory services.
      See Also: