public final class Connections extends Object
| 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 ConnectionFactory |
newAuthenticatedConnectionFactory(ConnectionFactory factory,
BindRequest request)
Creates a new authenticated connection factory which will obtain
connections using the provided connection factory and immediately perform
the provided Bind request.
|
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 ConnectionPool |
newFixedConnectionPool(ConnectionFactory factory,
int poolSize)
Creates a new connection pool which will maintain
poolSize
connections created using the provided connection factory. |
static ConnectionFactory |
newHeartBeatConnectionFactory(ConnectionFactory factory)
Creates a new heart-beat connection factory which will create connections
using the provided connection factory and periodically ping any created
connections in order to detect that they are still alive every 10 seconds
using the default scheduler.
|
static ConnectionFactory |
newHeartBeatConnectionFactory(ConnectionFactory factory,
long interval,
long timeout,
TimeUnit unit)
Creates a new heart-beat connection factory which will create connections
using the provided connection factory and periodically ping any created
connections in order to detect that they are still alive using the
specified frequency and the default scheduler.
|
static ConnectionFactory |
newHeartBeatConnectionFactory(ConnectionFactory factory,
long interval,
long timeout,
TimeUnit unit,
SearchRequest heartBeat)
Creates a new heart-beat connection factory which will create connections
using the provided connection factory and periodically ping any created
connections using the specified search request in order to detect that
they are still alive.
|
static ConnectionFactory |
newHeartBeatConnectionFactory(ConnectionFactory factory,
long interval,
long timeout,
TimeUnit unit,
SearchRequest heartBeat,
ScheduledExecutorService scheduler)
Creates a new heart-beat connection factory which will create connections
using the provided connection factory and periodically ping any created
connections using the specified search request in order to detect that
they are still alive.
|
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
RequestHandlers. |
static <C> ConnectionFactory |
newInternalConnectionFactory(RequestHandlerFactory<C,RequestContext> factory,
C clientContext)
Creates a new connection factory which binds internal client connections
to
RequestHandlers 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
ServerConnections created using the provided
ServerConnectionFactory. |
static ConnectionFactory |
newLoadBalancer(LoadBalancingAlgorithm algorithm)
Creates a new load balancer which will obtain connections using the
provided load balancing algorithm.
|
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 <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 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 ConnectionFactory newAuthenticatedConnectionFactory(ConnectionFactory factory, BindRequest request)
The connections returned by an authenticated connection factory 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.
factory - The connection factory to use for connecting to the Directory
Server.request - The Bind request to use for authentication.NullPointerException - If factory or request was null.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 ConnectionFactory newHeartBeatConnectionFactory(ConnectionFactory factory)
factory - The connection factory to use for creating connections.NullPointerException - If factory was null.public static ConnectionFactory newHeartBeatConnectionFactory(ConnectionFactory factory, long interval, long timeout, TimeUnit unit)
factory - The connection factory to use for creating connections.interval - The interval between keepalive pings.timeout - The heart-beat timeout after which a connection will be marked
as failed.unit - The time unit for the interval between keepalive pings.IllegalArgumentException - If interval was negative.NullPointerException - If factory or unit was null.public static ConnectionFactory newHeartBeatConnectionFactory(ConnectionFactory factory, long interval, long timeout, TimeUnit unit, SearchRequest heartBeat)
factory - The connection factory to use for creating connections.interval - The interval between keepalive pings.timeout - The heart-beat timeout after which a connection will be marked
as failed.unit - The time unit for the interval between keepalive pings.heartBeat - The search request to use for keepalive pings.IllegalArgumentException - If interval was negative.NullPointerException - If factory, unit, or heartBeat was
null.public static ConnectionFactory newHeartBeatConnectionFactory(ConnectionFactory factory, long interval, long timeout, TimeUnit unit, SearchRequest heartBeat, ScheduledExecutorService scheduler)
factory - The connection factory to use for creating connections.interval - The interval between keepalive pings.timeout - The heart-beat timeout after which a connection will be marked
as failed.unit - The time unit for the interval between keepalive pings.heartBeat - The search request to use for keepalive pings.scheduler - The scheduler which should for periodically sending keepalive
pings.IllegalArgumentException - If interval was negative.NullPointerException - If factory, unit, or heartBeat 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)
RequestHandlers.
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)
RequestHandlers 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)
ServerConnections 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 newLoadBalancer(LoadBalancingAlgorithm algorithm)
algorithm - The load balancing algorithm which will be used to obtain the
nextNullPointerException - If algorithm was null.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 or not 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 or not 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 © 2011-2015 ForgeRock AS. All Rights Reserved.