public final class LdapClients extends Object
Modifier and Type | Field and Description |
---|---|
static Option<DecodeOptions> |
DECODE_OPTIONS
Sets the decoding options which will be used to control how requests and responses are decoded.
|
static Option<BindRequest> |
LDAP_CLIENT_AUTHN_BIND_REQUEST
Configures the connection factory to return pre-authenticated connections using the specified
BindRequest . |
static 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 . |
static Option<Duration> |
LDAP_CLIENT_CONNECT_TIMEOUT
Specifies the connect timeout specified.
|
static Option<Boolean> |
LDAP_CLIENT_HEARTBEAT_ENABLED
Configures the connection factory to periodically send "heart-beat" or "keep-alive" requests to the Directory
Server.
|
static Option<Duration> |
LDAP_CLIENT_HEARTBEAT_INTERVAL
Specifies the time between successive heart-beat requests (default interval is 10 seconds).
|
static Option<ScheduledExecutorService> |
LDAP_CLIENT_HEARTBEAT_SCHEDULER
Specifies the scheduler which will be used for periodically sending heart-beat requests.
|
static Option<SearchRequest> |
LDAP_CLIENT_HEARTBEAT_SEARCH_REQUEST
Specifies the parameters of the search request that will be used for heart-beats.
|
static 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).
|
static Option<Integer> |
LDAP_CLIENT_MAX_CONCURRENT_REQUESTS
Specifies the maximum number of concurrent requests per connection.
|
static Option<Duration> |
LDAP_CLIENT_REQUEST_TIMEOUT
Specifies the operation timeout.
|
static Option<Boolean> |
LDAP_CLIENT_SSL_USE_STARTTLS
Specifies whether SSL or StartTLS should be used for securing connections when an SSL context is specified.
|
static 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.
|
static Option<IntUnaryOperator> |
LOAD_BALANCER_IDLE_SERVER_SELECTOR
Specifies a function to chose a server when all servers are idle.
|
static Option<Duration> |
LOAD_BALANCER_MONITORING_INTERVAL
Specifies the interval between successive attempts to reconnect to offline load-balanced LDAP clients.
|
static Option<Collection<Dn>> |
LOAD_BALANCER_PARTITION_BASE_DNS
Specifies partition base DNs.
|
static Option<ScheduledExecutorService> |
LOAD_BALANCER_SCHEDULER
Specifies the scheduler which will be used for periodically reconnecting to offline LDAP clients.
|
static Option<IntConsumer> |
PROBE_BYTES_READ
Callback invoked each time this server read bytes from the network.
|
static Option<IntConsumer> |
PROBE_BYTES_WRITTEN
Callback invoked each time this server write bytes to the network.
|
static Option<Boolean> |
SO_KEEPALIVE
Specifies the value of the
SO_KEEPALIVE socket option for new connections. |
static Option<Integer> |
SO_LINGER_IN_SECONDS
Specifies the value of the
SO_LINGER socket option for new connections. |
static Option<Boolean> |
SO_REUSE_ADDRESS
Specifies the value of the
SO_REUSEADDR socket option for new connections. |
static Option<SslOptions> |
SSL_OPTIONS
Specifies the options to use for the SSL support or
null if SSL is disabled. |
static Option<Boolean> |
TCP_NO_DELAY
Specifies the value of the
TCP_NODELAY socket option for new connections. |
static Option<String> |
TRANSPORT_PROVIDER
Specifies the name of the provider to use for transport.
|
static Option<ClassLoader> |
TRANSPORT_PROVIDER_CLASS_LOADER
Specifies the class loader which will be used to load the
TransportProvider . |
Modifier and Type | Method and Description |
---|---|
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.
|
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.
|
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.
|
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.
|
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.
|
static ConnectionPool |
newFixedConnectionPool(LdapClient client,
int poolSize)
Creates a new connection pool which will maintain
poolSize
connections created using the provided LDAP client. |
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.
|
static LdapClient |
newInternalLdapClient(BiFunction<Integer,Request,Flowable<Response>> requestHandler)
Creates a new
LdapClient which will route requests to the provided requestHandler . |
static LdapClientSocket |
newInternalLdapClientSocket(BiFunction<Integer,Request,Flowable<Response>> requestHandler)
Creates a new
LdapClientSocket which will route requests to the provided requestHandler . |
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.
|
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.
|
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.
|
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 . |
static LdapClient |
newNullLdapClient()
Returns an LDAP client which always throws
ResultCode.CLIENT_SIDE_CONNECT_ERROR ,
without any error message. |
static LdapClient |
newNullLdapClient(String name,
LocalizableMessage connectErrorMessage)
Returns an LDAP client which always throws
ResultCode.CLIENT_SIDE_CONNECT_ERROR
using the provided error message. |
static LdapClientSocket |
uncloseable(LdapClientSocket socket)
Returns an uncloseable view of the provided socket.
|
public static final Option<Duration> LOAD_BALANCER_MONITORING_INTERVAL
public static final Option<LoadBalancerEventListener> LOAD_BALANCER_EVENT_LISTENER
LoadBalancingAlgorithm
logger using the LoadBalancerEventListener.LOG_EVENTS
listener.public static final Option<ScheduledExecutorService> LOAD_BALANCER_SCHEDULER
public static final Option<IntUnaryOperator> LOAD_BALANCER_IDLE_SERVER_SELECTOR
public static final Option<Collection<Dn>> LOAD_BALANCER_PARTITION_BASE_DNS
public static final Option<Duration> LDAP_CLIENT_CONNECT_TIMEOUT
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.
public static final Option<Duration> LDAP_CLIENT_REQUEST_TIMEOUT
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.
public static final Option<Integer> LDAP_CLIENT_MAX_CONCURRENT_REQUESTS
LdapClientSocket.send(Request, RequestHandle)
will stop sending requests.public static final Option<BindRequest> LDAP_CLIENT_AUTHN_BIND_REQUEST
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.
public static final Option<Supplier<BindRequest>> LDAP_CLIENT_AUTHN_BIND_REQUEST_FACTORY
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.
public static final Option<Boolean> LDAP_CLIENT_HEARTBEAT_ENABLED
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
ConnectionEventListener
s. 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.
public static final Option<Duration> LDAP_CLIENT_HEARTBEAT_INTERVAL
LDAP_CLIENT_HEARTBEAT_ENABLED
is set to true
.LDAP_CLIENT_HEARTBEAT_ENABLED
public static final Option<ScheduledExecutorService> LDAP_CLIENT_HEARTBEAT_SCHEDULER
LDAP_CLIENT_HEARTBEAT_ENABLED
is set to
true
.LDAP_CLIENT_HEARTBEAT_ENABLED
public static final Option<Duration> LDAP_CLIENT_HEARTBEAT_TIMEOUT
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.LDAP_CLIENT_HEARTBEAT_ENABLED
public static final Option<Boolean> LDAP_CLIENT_SSL_USE_STARTTLS
By default SSL will be used in preference to StartTLS.
public static final Option<SearchRequest> LDAP_CLIENT_HEARTBEAT_SEARCH_REQUEST
LDAP_CLIENT_HEARTBEAT_ENABLED
is set to true
.LDAP_CLIENT_HEARTBEAT_ENABLED
public static final Option<ClassLoader> TRANSPORT_PROVIDER_CLASS_LOADER
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.
public static final Option<String> TRANSPORT_PROVIDER
Transport providers implement TransportProvider
interface.
The name should correspond to the name of an existing provider, as
returned by TransportProvider#getName()
method.
public static final Option<Boolean> TCP_NO_DELAY
TCP_NODELAY
socket option for new connections.
The default setting is true
and may be configured using the
org.forgerock.opendj.transport.tcpNoDelay
property.
public static final Option<Boolean> SO_REUSE_ADDRESS
SO_REUSEADDR
socket option for new connections.
The default setting is true
and may be configured using the
org.forgerock.opendj.transport.reuseAddress
property.
public static final Option<Integer> SO_LINGER_IN_SECONDS
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.
public static final Option<Boolean> SO_KEEPALIVE
SO_KEEPALIVE
socket option for new connections.
The default setting is true
and may be configured using the
org.forgerock.opendj.transport.keepAlive
property.
public static final Option<DecodeOptions> DECODE_OPTIONS
public static final Option<SslOptions> SSL_OPTIONS
null
if SSL is disabled.public static final Option<IntConsumer> PROBE_BYTES_READ
public static final Option<IntConsumer> PROBE_BYTES_WRITTEN
public static LdapClient newLdapClient(String host, int port)
host
- The host name.port
- The port number.NullPointerException
- If host
was null
.ProviderNotFoundException
- if no provider is available or if the provider requested using options is not found.LDAP_CLIENT_AUTHN_BIND_REQUEST
,
LDAP_CLIENT_CONNECT_TIMEOUT
,
LDAP_CLIENT_HEARTBEAT_ENABLED
,
LDAP_CLIENT_HEARTBEAT_INTERVAL
,
LDAP_CLIENT_HEARTBEAT_SCHEDULER
,
LDAP_CLIENT_HEARTBEAT_SEARCH_REQUEST
,
LDAP_CLIENT_HEARTBEAT_TIMEOUT
,
LDAP_CLIENT_MAX_CONCURRENT_REQUESTS
,
LDAP_CLIENT_REQUEST_TIMEOUT
,
LDAP_CLIENT_SSL_USE_STARTTLS
,
DECODE_OPTIONS
,
SO_KEEPALIVE
,
SO_LINGER_IN_SECONDS
,
SO_REUSE_ADDRESS
,
SSL_OPTIONS
,
TCP_NO_DELAY
,
TRANSPORT_PROVIDER
,
TRANSPORT_PROVIDER_CLASS_LOADER
,
TRANSPORT_PROVIDER_INSTANCE
public static LdapClient newLdapClient(String host, int port, Options options)
host
- The host name.port
- The port number.options
- The LDAP options to use when creating connections.NullPointerException
- If host
or options
was null
.ProviderNotFoundException
- if no provider is available or if the provider requested using options is not found.LDAP_CLIENT_AUTHN_BIND_REQUEST
,
LDAP_CLIENT_CONNECT_TIMEOUT
,
LDAP_CLIENT_HEARTBEAT_ENABLED
,
LDAP_CLIENT_HEARTBEAT_INTERVAL
,
LDAP_CLIENT_HEARTBEAT_SCHEDULER
,
LDAP_CLIENT_HEARTBEAT_SEARCH_REQUEST
,
LDAP_CLIENT_HEARTBEAT_TIMEOUT
,
LDAP_CLIENT_MAX_CONCURRENT_REQUESTS
,
LDAP_CLIENT_REQUEST_TIMEOUT
,
LDAP_CLIENT_SSL_USE_STARTTLS
,
DECODE_OPTIONS
,
SO_KEEPALIVE
,
SO_LINGER_IN_SECONDS
,
SO_REUSE_ADDRESS
,
SSL_OPTIONS
,
TCP_NO_DELAY
,
TRANSPORT_PROVIDER
,
TRANSPORT_PROVIDER_CLASS_LOADER
,
TRANSPORT_PROVIDER_INSTANCE
public static LdapClient newAffinityRequestLoadBalancer(Collection<? extends LdapClient> clients, Options options)
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.
clients
- The LDAP clients.options
- This configuration options for the load-balancer.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
public static ConnectionPool newCachedConnectionPool(LdapClient client)
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
.
client
- The LDAP client to use for creating new connections.NullPointerException
- If client
was null
.public static ConnectionPool newCachedConnectionPool(LdapClient client, int corePoolSize, int maximumPoolSize, long idleTimeout, TimeUnit unit)
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
.
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.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
.public static ConnectionPool newCachedConnectionPool(LdapClient client, int corePoolSize, int maximumPoolSize, long idleTimeout, TimeUnit unit, ScheduledExecutorService scheduler)
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
.
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.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
.public static LdapClient newFailoverLoadBalancer(Collection<? extends LdapClient> clients, Options options)
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.
clients
- The LDAP clients.options
- This configuration options for the load-balancer.newAffinityRequestLoadBalancer(Collection, Options)
,
newLeastRequestsLoadBalancer(Collection, Options)
,
LOAD_BALANCER_EVENT_LISTENER
,
LOAD_BALANCER_MONITORING_INTERVAL
,
LOAD_BALANCER_SCHEDULER
,
LOAD_BALANCER_IDLE_SERVER_SELECTOR
public static ConnectionPool newFixedConnectionPool(LdapClient client, int poolSize)
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
.
client
- The LDAP client to use for creating new connections.poolSize
- The maximum size of the connection pool.IllegalArgumentException
- If poolSize
is negative.NullPointerException
- If client
was null
.public static LdapClient newFixedSizeDistributionLoadBalancer(Set<Dn> partitionBaseDns, ConsistentHashMap<? extends LdapClient> partitions, Options options)
NOTE: there are a number of assumptions in the design of this load balancer as well as a number of limitations:
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).public static LdapClientSocket newInternalLdapClientSocket(BiFunction<Integer,Request,Flowable<Response>> requestHandler)
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.
requestHandler
- The request handler which will be used for all client connections.NullPointerException
- If requestHandler
was null
.public static LdapClient newInternalLdapClient(BiFunction<Integer,Request,Flowable<Response>> requestHandler)
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.
requestHandler
- The request handler which will be used for all client connections.NullPointerException
- If requestHandler
was null
.public static LdapClient newLeastRequestsLoadBalancer(Collection<? extends LdapClient> clients, Options options)
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.
clients
- The LDAP clients.options
- This configuration options for the load-balancer.newFailoverLoadBalancer(Collection, Options)
,
newAffinityRequestLoadBalancer(Collection, Options)
,
LOAD_BALANCER_EVENT_LISTENER
,
LOAD_BALANCER_MONITORING_INTERVAL
,
LOAD_BALANCER_SCHEDULER
,
LOAD_BALANCER_IDLE_SERVER_SELECTOR
public static LdapClient newNamedLdapClient(LdapClient client, String name)
toString
method will always return name
.
This method may be useful for debugging purposes in order to more easily identity LDAP clients.
client
- The LDAP client to be named.name
- The name of the LDAP client.NullPointerException
- If client
or name
was null
.public static LdapClient newNullLdapClient()
ResultCode.CLIENT_SIDE_CONNECT_ERROR
,
without any error message.public static LdapClient newNullLdapClient(String name, LocalizableMessage connectErrorMessage)
ResultCode.CLIENT_SIDE_CONNECT_ERROR
using the provided error message.name
- The name of the LDAP client.connectErrorMessage
- The error message to use when returning ResultCode.CLIENT_SIDE_CONNECT_ERROR
.public static LdapClientSocket uncloseable(LdapClientSocket socket)
LdapClientSocket.close()
or
LdapClientSocket.close(UnbindRequest, String)
will be ignored.socket
- The socket whose close
methods are to be disabled.Copyright 2010-2022 ForgeRock AS.