Package org.forgerock.opendj.ldap

Class LdapClients

  • public final class LdapClients
extends Object
    This class contains methods for creating and manipulating LDAP clients and connections.

    • Field Detail

      • 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_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_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_ENABLE_PRE_AUTHENTICATION

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

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

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

    • Method Detail

      • newAffinityRequestLoadBalancer

        public static LdapClient newAffinityRequestLoadBalancer​(Collection<? 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:
        newFailoverLoadBalancer(Collection, Options), newLeastRequestsLoadBalancer(Collection, Options), LOAD_BALANCER_EVENT_LISTENER, LOAD_BALANCER_AVAILABILITY_CHECK_INTERVAL, LOAD_BALANCER_AVAILABILITY_CHECK_SEARCH_REQUEST, LOAD_BALANCER_AVAILABILITY_CHECK_TIMEOUT, LOAD_BALANCER_SCHEDULER, LOAD_BALANCER_PARTITION_BASE_DNS

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

      • 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:
        newAffinityRequestLoadBalancer(Collection, Options), newLeastRequestsLoadBalancer(Collection, Options), LOAD_BALANCER_EVENT_LISTENER, LOAD_BALANCER_AVAILABILITY_CHECK_INTERVAL, LOAD_BALANCER_AVAILABILITY_CHECK_SEARCH_REQUEST, LOAD_BALANCER_AVAILABILITY_CHECK_TIMEOUT, LOAD_BALANCER_SCHEDULER

      • 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​(io.reactivex.rxjava3.functions.BiFunction<Integer,​Request,​io.reactivex.rxjava3.core.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​(io.reactivex.rxjava3.functions.BiFunction<Integer,​Request,​io.reactivex.rxjava3.core.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:
        newFailoverLoadBalancer(Collection, Options), newAffinityRequestLoadBalancer(Collection, Options), LOAD_BALANCER_EVENT_LISTENER, LOAD_BALANCER_AVAILABILITY_CHECK_INTERVAL, LOAD_BALANCER_AVAILABILITY_CHECK_SEARCH_REQUEST, LOAD_BALANCER_AVAILABILITY_CHECK_TIMEOUT, LOAD_BALANCER_SCHEDULER

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