public final class Connections extends Object
Modifier and Type | Field and Description |
---|---|
static Option<LoadBalancerEventListener> |
LOAD_BALANCER_EVENT_LISTENER
Specifies the event listener which should be notified whenever a load-balanced connection factory changes state
from online to offline or vice-versa.
|
static Option<Duration> |
LOAD_BALANCER_MONITORING_INTERVAL
Specifies the interval between successive attempts to reconnect to offline load-balanced connection factories.
|
static Option<ScheduledExecutorService> |
LOAD_BALANCER_SCHEDULER
Specifies the scheduler which will be used for periodically reconnecting to offline connection factories.
|
Modifier and Type | Method and Description |
---|---|
static String |
getHostString(InetSocketAddress socketAddress)
Returns the host name associated with the provided
InetSocketAddress , without performing a DNS lookup. |
static ConnectionPool |
newCachedConnectionPool(ConnectionFactory factory)
Creates a new connection pool which creates new connections as needed
using the provided connection factory, but will reuse previously
allocated connections when they are available.
|
static ConnectionPool |
newCachedConnectionPool(ConnectionFactory factory,
int corePoolSize,
int maximumPoolSize,
long idleTimeout,
TimeUnit unit)
Creates a new connection pool which creates new connections as needed
using the provided connection factory, but will reuse previously
allocated connections when they are available.
|
static ConnectionPool |
newCachedConnectionPool(ConnectionFactory factory,
int corePoolSize,
int maximumPoolSize,
long idleTimeout,
TimeUnit unit,
ScheduledExecutorService scheduler)
Creates a new connection pool which creates new connections as needed
using the provided connection factory, but will reuse previously
allocated connections when they are available.
|
static ConnectionFactory |
newFailoverLoadBalancer(Collection<? extends ConnectionFactory> factories,
Options options)
Creates a new "fail-over" load-balancer which will load-balance connections across the provided set of connection
factories.
|
static ConnectionPool |
newFixedConnectionPool(ConnectionFactory factory,
int poolSize)
Creates a new connection pool which will maintain
poolSize
connections created using the provided connection factory. |
static Connection |
newInternalConnection(RequestHandler<RequestContext> requestHandler)
Creates a new internal client connection which will route requests to the
provided
RequestHandler . |
static Connection |
newInternalConnection(ServerConnection<Integer> serverConnection)
Creates a new internal client connection which will route requests to the
provided
ServerConnection . |
static ConnectionFactory |
newInternalConnectionFactory(RequestHandler<RequestContext> requestHandler)
Creates a new connection factory which binds internal client connections
to the provided
RequestHandler s. |
static <C> ConnectionFactory |
newInternalConnectionFactory(RequestHandlerFactory<C,RequestContext> factory,
C clientContext)
Creates a new connection factory which binds internal client connections
to
RequestHandler s created using the provided
RequestHandlerFactory . |
static <C> ConnectionFactory |
newInternalConnectionFactory(ServerConnectionFactory<C,Integer> factory,
C clientContext)
Creates a new connection factory which binds internal client connections
to
ServerConnection s created using the provided
ServerConnectionFactory . |
static ConnectionFactory |
newNamedConnectionFactory(ConnectionFactory factory,
String name)
Creates a new connection factory which forwards connection requests to
the provided factory, but whose
toString method will always
return name . |
static ConnectionFactory |
newRoundRobinLoadBalancer(Collection<? extends ConnectionFactory> factories,
Options options)
Creates a new "round-robin" load-balancer which will load-balance connections across the provided set of
connection factories.
|
static <C> ServerConnectionFactory<C,Integer> |
newServerConnectionFactory(RequestHandler<RequestContext> requestHandler)
Creates a new server connection factory using the provided
RequestHandler . |
static <C> ServerConnectionFactory<C,Integer> |
newServerConnectionFactory(RequestHandlerFactory<C,RequestContext> factory)
Creates a new server connection factory using the provided
RequestHandlerFactory . |
static ConnectionFactory |
newShardedRequestLoadBalancer(Collection<? extends ConnectionFactory> factories,
Options options)
Creates a new "sharded" load-balancer which will load-balance individual requests across the provided set of
connection factories, 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 Connection |
uncloseable(Connection connection)
Returns an uncloseable view of the provided connection.
|
static ConnectionFactory |
uncloseable(ConnectionFactory factory)
Returns an uncloseable view of the provided connection factory.
|
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 ConnectionPool newCachedConnectionPool(ConnectionFactory factory)
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
.
factory
- The connection factory to use for creating new connections.NullPointerException
- If factory
was null
.public static ConnectionPool newCachedConnectionPool(ConnectionFactory factory, 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
.
factory
- The connection factory 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 factory
was null
.public static ConnectionPool newCachedConnectionPool(ConnectionFactory factory, 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
.
factory
- The connection factory 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 factory
was null
.public static ConnectionPool newFixedConnectionPool(ConnectionFactory factory, int poolSize)
poolSize
connections created using the provided connection factory.
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
.
factory
- The connection factory to use for creating new connections.poolSize
- The maximum size of the connection pool.IllegalArgumentException
- If poolSize
is negative.NullPointerException
- If factory
was null
.public static Connection newInternalConnection(RequestHandler<RequestContext> requestHandler)
RequestHandler
.
When processing requests, RequestHandler
implementations are
passed a RequestContext
having a pseudo requestID
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 Connection newInternalConnection(ServerConnection<Integer> serverConnection)
ServerConnection
.
When processing requests, ServerConnection
implementations are
passed an integer as the first parameter. This integer represents a
pseudo requestID
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 ServerConnection
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.
serverConnection
- The server connection.NullPointerException
- If serverConnection
was null
.public static ConnectionFactory newInternalConnectionFactory(RequestHandler<RequestContext> requestHandler)
RequestHandler
s.
When processing requests, RequestHandler
implementations are
passed an integer as the first parameter. This integer represents a
pseudo requestID
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 factory 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 <C> ConnectionFactory newInternalConnectionFactory(RequestHandlerFactory<C,RequestContext> factory, C clientContext)
RequestHandler
s created using the provided
RequestHandlerFactory
.
When processing requests, RequestHandler
implementations are
passed an integer as the first parameter. This integer represents a
pseudo requestID
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 factory 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.
C
- The type of client context.factory
- The request handler factory to use for creating connections.clientContext
- The client context.NullPointerException
- If factory
was null
.public static <C> ConnectionFactory newInternalConnectionFactory(ServerConnectionFactory<C,Integer> factory, C clientContext)
ServerConnection
s created using the provided
ServerConnectionFactory
.
When processing requests, ServerConnection
implementations are
passed an integer as the first parameter. This integer represents a
pseudo requestID
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 factory does not require ServerConnection
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.
C
- The type of client context.factory
- The server connection factory to use for creating connections.clientContext
- The client context.NullPointerException
- If factory
was null
.public static ConnectionFactory newRoundRobinLoadBalancer(Collection<? extends ConnectionFactory> factories, Options options)
newFailoverLoadBalancer(Collection, Options)
which is used for load-balancing between data
centers.
If a problem occurs that temporarily prevents connections from being obtained for one of the connection
factories, then this algorithm automatically "fails over" to the next operational connection factory in the list.
If none of the connection factories are operational then a ConnectionException
is returned to the
client.
The implementation periodically attempts to connect to failed connection factories in order to determine if they
have become available again.factories
- The connection factories.options
- This configuration options for the load-balancer.newShardedRequestLoadBalancer(Collection, Options)
,
newFailoverLoadBalancer(Collection, Options)
,
LOAD_BALANCER_EVENT_LISTENER
,
LOAD_BALANCER_MONITORING_INTERVAL
,
LOAD_BALANCER_SCHEDULER
public static ConnectionFactory newFailoverLoadBalancer(Collection<? extends ConnectionFactory> factories, Options options)
newRoundRobinLoadBalancer(Collection, Options)
which is used for load-balancing within a data
center.
This algorithm selects connection factories based on the order in which they were provided during construction.
More specifically, an attempt to obtain a connection factory will always return the first operational
connection factory in the list. Applications should, therefore, organize the connection factories such that the
preferred (usually the closest) connection factories appear before those which are less preferred.
If a problem occurs that temporarily prevents connections from being obtained for one of the connection
factories, then this algorithm automatically "fails over" to the next operational connection factory in the list.
If none of the connection factories are operational then a ConnectionException
is returned to the
client.
The implementation periodically attempts to connect to failed connection factories in order to determine if they
have become available again.factories
- The connection factories.options
- This configuration options for the load-balancer.newRoundRobinLoadBalancer(Collection, Options)
,
newShardedRequestLoadBalancer(Collection, Options)
,
LOAD_BALANCER_EVENT_LISTENER
,
LOAD_BALANCER_MONITORING_INTERVAL
,
LOAD_BALANCER_SCHEDULER
public static ConnectionFactory newShardedRequestLoadBalancer(Collection<? extends ConnectionFactory> factories, Options options)
factories
- The connection factories.options
- This configuration options for the load-balancer.newRoundRobinLoadBalancer(Collection, Options)
,
newFailoverLoadBalancer(Collection, Options)
,
LOAD_BALANCER_EVENT_LISTENER
,
LOAD_BALANCER_MONITORING_INTERVAL
,
LOAD_BALANCER_SCHEDULER
public static ConnectionFactory newNamedConnectionFactory(ConnectionFactory factory, String name)
toString
method will always
return name
.
This method may be useful for debugging purposes in order to more easily identity connection factories.
factory
- The connection factory to be named.name
- The name of the connection factory.NullPointerException
- If factory
or name
was null
.public static <C> ServerConnectionFactory<C,Integer> newServerConnectionFactory(RequestHandler<RequestContext> requestHandler)
RequestHandler
. The returned factory will manage connection and
request life-cycle, including request cancellation.
When processing requests, RequestHandler
implementations are
passed a RequestContext
as the first parameter which may be used
for detecting whether the request should be aborted due to
cancellation requests or other events, such as connection failure.
The returned factory maintains state information which includes a table
of active requests. Therefore, RequestHandler
implementations are
required to always return results in order to avoid potential memory
leaks.
C
- The type of client context.requestHandler
- The request handler which will be used for all client
connections.NullPointerException
- If requestHandler
was null
.public static <C> ServerConnectionFactory<C,Integer> newServerConnectionFactory(RequestHandlerFactory<C,RequestContext> factory)
RequestHandlerFactory
. The returned factory will manage
connection and request life-cycle, including request cancellation.
When processing requests, RequestHandler
implementations are
passed a RequestContext
as the first parameter which may be used
for detecting whether the request should be aborted due to
cancellation requests or other events, such as connection failure.
The returned factory maintains state information which includes a table
of active requests. Therefore, RequestHandler
implementations are
required to always return results in order to avoid potential memory
leaks.
C
- The type of client context.factory
- The request handler factory to use for associating request
handlers with client connections.NullPointerException
- If factory
was null
.public static Connection uncloseable(Connection connection)
Connection.close()
or
Connection.close(org.forgerock.opendj.ldap.requests.UnbindRequest, String)
will be ignored.connection
- The connection whose close
methods are to be disabled.public static ConnectionFactory uncloseable(ConnectionFactory factory)
ConnectionFactory.close()
will be ignored.factory
- The connection factory whose close
method is to be
disabled.public static String getHostString(InetSocketAddress socketAddress)
InetSocketAddress
, without performing a DNS lookup. This method
attempts to provide functionality which is compatible with
InetSocketAddress.getHostString()
in JDK7. It can be removed once
we drop support for JDK6.socketAddress
- The socket address which is expected to be an instance of
InetSocketAddress
.SocketAddress
,
or null
if it is unknown.Copyright 2010-2017 ForgeRock AS.