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_MONITORING_INTERVAL

        public static final Option<Duration> LOAD_BALANCER_MONITORING_INTERVAL
        Specifies the interval between successive attempts to reconnect to offline load-balanced LDAP clients. The default configuration is to attempt to reconnect every second.

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

      • 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

        public static final Option<IntUnaryOperator> LOAD_BALANCER_IDLE_SERVER_SELECTOR
        Specifies a function to chose a server when all servers are idle.

      • LOAD_BALANCER_PARTITION_BASE_DNS

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

      • LDAP_CLIENT_CONNECT_TIMEOUT

        public static final Option<Duration> LDAP_CLIENT_CONNECT_TIMEOUT
        Specifies the connect timeout specified. 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.

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

      • LDAP_CLIENT_AUTHN_BIND_REQUEST_FACTORY

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

      • LDAP_CLIENT_HEARTBEAT_ENABLED

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

      • LDAP_CLIENT_HEARTBEAT_TIMEOUT

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

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

        public static final Option<SearchRequest> LDAP_CLIENT_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 LDAP_CLIENT_HEARTBEAT_ENABLED is set to true.
        See Also:
        LDAP_CLIENT_HEARTBEAT_ENABLED

      • TRANSPORT_PROVIDER_CLASS_LOADER

        public static final Option<ClassLoader> TRANSPORT_PROVIDER_CLASS_LOADER
        Specifies the class loader which will be used to load the TransportProvider.

        By default the default class loader will be used.

        The transport provider is loaded using java.util.ServiceLoader, the JDK service-provider loading facility. The provider must be accessible from the same class loader that was initially queried to locate the configuration file; note that this is not necessarily the class loader from which the file was actually loaded. This method allows to provide a class loader to be used for loading the provider.

      • TRANSPORT_PROVIDER

        public static final Option<String> TRANSPORT_PROVIDER
        Specifies the name of the provider to use for transport.

        Transport providers implement TransportProvider interface.

        The name should correspond to the name of an existing provider, as returned by TransportProvider#getName() method.

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

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

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

    • 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_MONITORING_INTERVAL, LOAD_BALANCER_SCHEDULER, LOAD_BALANCER_PARTITION_BASE_DNS, LOAD_BALANCER_IDLE_SERVER_SELECTOR

      • 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_MONITORING_INTERVAL, LOAD_BALANCER_SCHEDULER, LOAD_BALANCER_IDLE_SERVER_SELECTOR

      • 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:
        newFailoverLoadBalancer(Collection, Options), newAffinityRequestLoadBalancer(Collection, Options), LOAD_BALANCER_EVENT_LISTENER, LOAD_BALANCER_MONITORING_INTERVAL, LOAD_BALANCER_SCHEDULER, LOAD_BALANCER_IDLE_SERVER_SELECTOR

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