Package org.forgerock.opendj.ldap

Class Connections

java.lang.Object
org.forgerock.opendj.ldap.Connections
public final class Connections extends Object
This class contains methods for creating and manipulating connection factories and connections.

  • Field Details

    • LOAD_BALANCER_MONITORING_INTERVAL

      public static final org.forgerock.util.Option<org.forgerock.util.time.Duration> LOAD_BALANCER_MONITORING_INTERVAL
      Specifies the interval between successive attempts to reconnect to offline load-balanced connection factories. The default configuration is to attempt to reconnect every second.

    • LOAD_BALANCER_EVENT_LISTENER

      public static final org.forgerock.util.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. By default events will be logged to the LoadBalancingAlgorithm logger using the LoadBalancerEventListener.LOG_EVENTS listener.

    • LOAD_BALANCER_SCHEDULER

      public static final org.forgerock.util.Option<ScheduledExecutorService> LOAD_BALANCER_SCHEDULER
      Specifies the scheduler which will be used for periodically reconnecting to offline connection factories. A system-wide scheduler will be used by default.

  • Method Details

    • newCachedConnectionPool

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

      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:
      factory - The connection factory to use for creating new connections.
      Returns:
      The new connection pool.
      Throws:
      NullPointerException - If factory was null.

    • newCachedConnectionPool

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

      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:
      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.
      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 factory was null.

    • newCachedConnectionPool

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

      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:
      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.
      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 factory was null.

    • newFixedConnectionPool

      public static ConnectionPool newFixedConnectionPool(ConnectionFactory factory, int poolSize)
      Creates a new connection pool which will maintain 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.

      Parameters:
      factory - The connection factory 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 factory was null.

    • newInternalConnection

      public static Connection newInternalConnection(RequestHandler<RequestContext> requestHandler)
      Creates a new internal client connection which will route requests to the provided 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.

      Parameters:
      requestHandler - The request handler which will be used for all client connections.
      Returns:
      The new internal connection.
      Throws:
      NullPointerException - If requestHandler was null.

    • newInternalConnection

      public static Connection newInternalConnection(ServerConnection<Integer> serverConnection)
      Creates a new internal client connection which will route requests to the provided 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.

      Parameters:
      serverConnection - The server connection.
      Returns:
      The new internal connection.
      Throws:
      NullPointerException - If serverConnection was null.

    • newInternalConnectionFactory

      public static ConnectionFactory newInternalConnectionFactory(RequestHandler<RequestContext> requestHandler)
      Creates a new connection factory which binds internal client connections to the provided 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.

      Parameters:
      requestHandler - The request handler which will be used for all client connections.
      Returns:
      The new internal connection factory.
      Throws:
      NullPointerException - If requestHandler was null.

    • newInternalConnectionFactory

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

      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.

      Type Parameters:
      C - The type of client context.
      Parameters:
      factory - The request handler factory to use for creating connections.
      clientContext - The client context.
      Returns:
      The new internal connection factory.
      Throws:
      NullPointerException - If factory was null.

    • newInternalConnectionFactory

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

      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.

      Type Parameters:
      C - The type of client context.
      Parameters:
      factory - The server connection factory to use for creating connections.
      clientContext - The client context.
      Returns:
      The new internal connection factory.
      Throws:
      NullPointerException - If factory was null.

    • newRoundRobinLoadBalancer

      public static ConnectionFactory newRoundRobinLoadBalancer(Collection<? extends ConnectionFactory> factories, org.forgerock.util.Options options)
      Creates a new "round-robin" load-balancer which will load-balance connections across the provided set of connection factories. A round robin load balancing algorithm distributes connection requests across a list of connection factories one at a time. When the end of the list is reached, the algorithm starts again from the beginning.

      This algorithm is typically used for load-balancing within data centers, where load must be distributed equally across multiple data sources. This algorithm contrasts with the 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.

      Parameters:
      factories - The connection factories.
      options - This configuration options for the load-balancer.
      Returns:
      The new round-robin load balancer.
      See Also:

    • newFailoverLoadBalancer

      public static ConnectionFactory newFailoverLoadBalancer(Collection<? extends ConnectionFactory> factories, org.forgerock.util.Options options)
      Creates a new "fail-over" load-balancer which will load-balance connections across the provided set of connection factories. A fail-over load balancing algorithm provides fault tolerance across multiple underlying connection factories.

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

      Parameters:
      factories - The connection factories.
      options - This configuration options for the load-balancer.
      Returns:
      The new fail-over load balancer.
      See Also:

    • newAffinityRequestLoadBalancer

      public static ConnectionFactory newAffinityRequestLoadBalancer(Collection<? extends ConnectionFactory> factories, org.forgerock.util.Options options)
      Creates a new "affinity" 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. 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 connection factory 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 connection factories are unavailable.

      NOTE: in deployments where there are multiple client applications, care should be taken to ensure that the factories are configured using the same ordering, otherwise requests will not be routed consistently across the client applications.

      The implementation periodically attempts to connect to failed connection factories in order to determine if they have become available again.

      Parameters:
      factories - The connection factories.
      options - This configuration options for the load-balancer.
      Returns:
      The new affinity load balancer.
      See Also:

    • newFixedSizeDistributionLoadBalancer

      public static ConnectionFactory newFixedSizeDistributionLoadBalancer(DN partitionBaseDN, ConsistentHashMap<? extends ConnectionFactory> partitions, org.forgerock.util.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 the 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 the 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:
      partitionBaseDN - The DN 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.

    • newLeastRequestsLoadBalancer

      public static ConnectionFactory newLeastRequestsLoadBalancer(Collection<? extends ConnectionFactory> factories, org.forgerock.util.Options options)
      Creates a new "least requests" 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 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 connection factory 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 connection factories 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 to failed connection factories in order to determine if they have become available again.

      Parameters:
      factories - The connection factories.
      options - This configuration options for the load-balancer.
      Returns:
      The new least requests load balancer.
      See Also:

    • newNamedConnectionFactory

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

      This method may be useful for debugging purposes in order to more easily identity connection factories.

      Parameters:
      factory - The connection factory to be named.
      name - The name of the connection factory.
      Returns:
      The named connection factory.
      Throws:
      NullPointerException - If factory or name was null.

    • newServerConnectionFactory

      public static <C> ServerConnectionFactory<C,Integer> newServerConnectionFactory(RequestHandler<RequestContext> requestHandler)
      Creates a new server connection factory using the provided 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.

      Type Parameters:
      C - The type of client context.
      Parameters:
      requestHandler - The request handler which will be used for all client connections.
      Returns:
      The new server connection factory.
      Throws:
      NullPointerException - If requestHandler was null.

    • newServerConnectionFactory

      public static <C> ServerConnectionFactory<C,Integer> newServerConnectionFactory(RequestHandlerFactory<C,RequestContext> factory)
      Creates a new server connection factory using the provided 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.

      Type Parameters:
      C - The type of client context.
      Parameters:
      factory - The request handler factory to use for associating request handlers with client connections.
      Returns:
      The new server connection factory.
      Throws:
      NullPointerException - If factory was null.

    • uncloseable

      public static Connection uncloseable(Connection connection)
      Returns an uncloseable view of the provided connection. Attempts to call Connection.close() or Connection.close(org.forgerock.opendj.ldap.requests.UnbindRequest, String) will be ignored.
      Parameters:
      connection - The connection whose close methods are to be disabled.
      Returns:
      An uncloseable view of the provided connection.

    • uncloseable

      public static ConnectionFactory uncloseable(ConnectionFactory factory)
      Returns an uncloseable view of the provided connection factory. Attempts to call ConnectionFactory.close() will be ignored.
      Parameters:
      factory - The connection factory whose close method is to be disabled.
      Returns:
      An uncloseable view of the provided connection factory.

    • getHostString

      public static String getHostString(InetSocketAddress socketAddress)
      Returns the host name associated with the provided 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.
      Parameters:
      socketAddress - The socket address which is expected to be an instance of InetSocketAddress.
      Returns:
      The host name associated with the provided SocketAddress, or null if it is unknown.