Package com.unboundid.ldap.sdk

Class PooledReferralConnector

java.lang.Object
com.unboundid.ldap.sdk.PooledReferralConnector
All Implemented Interfaces:
ReferralConnector, ReusableReferralConnector, Closeable, AutoCloseable
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class PooledReferralConnector extends Object implements ReusableReferralConnector, Closeable
This class provides an implementation of a reusable referral connector that maintains pools of connections to each of the servers accessed in the course of following referrals. Connections may be reused across multiple referrals. Note that it is important to close the connector when it is no longer needed, as that will ensure that all of the connection pools that it maintains will be closed.

Example

The following example demonstrates the process for establishing an LDAP connection that will use this connector for following any referrals that are encountered during processing: 
   PooledReferralConnectorProperties properties =
        new PooledReferralConnectorProperties();

   PooledReferralConnector referralConnector =
        new PooledReferralConnector(properties);

   LDAPConnectionOptions options = new LDAPConnectionOptions();
   options.setFollowReferrals(true);
   options.setReferralConnector(referralConnector);

   try (LDAPConnection conn = new LDAPConnection(socketFactory, options,
             serverAddress, serverPort)
   {
     // Use the connection to perform whatever processing is needed that might
     // involve receiving referrals.
   }
   finally
   {
     referralConnector.close();
   }

  • Constructor Details

  • Method Details

    • getInitialConnectionsPerPool

      public int getInitialConnectionsPerPool()
      Retrieves the initial number of connections to establish when creating a new connection pool for the purpose of following referrals. By default, only a single connection will be established.
      Returns:
      The initial number of connections to establish when creating a new connection pool for the purpose of following referrals.

    • getMaximumConnectionsPerPool

      public int getMaximumConnectionsPerPool()
      Retrieves the maximum number of idle connections that the server should maintain in each connection pool used for following referrals. By default, a maximum of ten connections will be retained.
      Returns:
      The maximum number of idle connections that the server should maintain in each connection pool used for following referrals.

    • retryFailedOperationsDueToInvalidConnections

      public boolean retryFailedOperationsDueToInvalidConnections()
      Indicates whether the connection pools should be configured to automatically retry an operation on a newly established connection if the initial attempt fails in a manner that suggests that the connection may no longer be valid. By default, operations that fail in that manner will automatically be retried.
      Returns:
      true if connection pools should be configured to automatically retry an operation on a newly established connection if the initial attempt fails in a manner that suggests the connection may no longer be valid, or false if not.

    • getMaximumConnectionAgeMillis

      public long getMaximumConnectionAgeMillis()
      Retrieves the maximum length of time in milliseconds that each pooled connection may remain established. If a pooled connection is established for longer than this duration, it will be closed and re-established. By default, pooled connections will be allowed to remain established for up to 30 minutes. A value of zero indicates that pooled connections will be allowed to remain established indefinitely (or at least until it is determined to be invalid or the pool is closed).
      Returns:
      The maximum length of time in milliseconds that each pooled connection may remain established.

    • getMaximumPoolAgeMillis

      public long getMaximumPoolAgeMillis()
      Retrieves the maximum length of time in milliseconds that a connection pool created for the purpose of following referrals should be retained, regardless of how often it is used. If it has been longer than this length of time since a referral connection pool was created, it will be automatically closed, and a new pool will be created if another applicable referral is received. A value of zero, which is the default, indicates that connection pools should not be automatically closed based on the length of time since they were created.
      Returns:
      The maximum length of time in milliseconds that a referral connection pool should be retained, or zero if connection pools should not be automatically closed based on the length of time since they were created.

    • getMaximumPoolIdleDurationMillis

      public long getMaximumPoolIdleDurationMillis()
      Retrieves the maximum length of time in milliseconds that a connection pool created for the purpose of following referrals should be retained after its most recent use. By default, referral connection pools will be automatically discarded if they have remained unused for over one hour. A value of zero indicates that pools may remain in use indefinitely, regardless of how long it has been since they were last used.
      Returns:
      The maximum length of time in milliseconds that a connection pool created for the purpose of following referrals should be retained after its most recent use, or zero if referral connection pools should not be discarded regardless of how long it has been since they were last used.

    • getHealthCheck

      @Nullable public LDAPConnectionPoolHealthCheck getHealthCheck()
      Retrieves the health check that should be used to determine whether pooled connections are still valid. By default, no special health checking will be performed for pooled connections (aside from checking them against the maximum connection age).
      Returns:
      The health check that should be used to determine whether pooled connections are still valid, or null if no special health checking should be performed.

    • getHealthCheckIntervalMillis

      public long getHealthCheckIntervalMillis()
      Retrieves the length of time in milliseconds between background health checks performed against pooled connections. By default, background health checks will be performed every sixty seconds.
      Returns:
      The length of time in milliseconds between background health checks performed against pooled connections.

    • getBindRequest

      @Nullable public BindRequest getBindRequest()
      Retrieves the bind request that should be used to authenticate pooled connections, if defined. By default, pooled connections will be authenticated with the same bind request that was used to authenticate the connection on which the referral was received (with separate pools used for referrals received on connections authenticated as different users).
      Returns:
      The bind request that should be used to authenticate pooled connections, or null if pooled connections should be authenticated with the same bind request that was used to authenticate the connection on which the referral was received.

    • getConnectionOptions

      @Nullable public LDAPConnectionOptions getConnectionOptions()
      Retrieves the set of options that will be used when establishing new pooled connections for the purpose of following referrals. By default, new connections will use the same set of options as the connection on which a referral was received.
      Returns:
      The set of options that will be used when establishing new pooled connections for the purpose of following referrals, or null if new connections will use the same set of options as the connection on which a referral was received.

    • getLDAPURLSecurityType

      @NotNull public PooledReferralConnectorLDAPURLSecurityType getLDAPURLSecurityType()
      Indicates the type of communication security that the referral connector should use when creating connections for referral URLs with a scheme of "ldap". Although the connector will always use LDAPS for connections created from referral URLs with a scheme of "ldaps", the determination of which security type to use for referral URLs with a scheme of "ldap" is more complicated because the official LDAP URL specification lists "ldap" as the only allowed scheme type. See the class-level and value-level documentation in the PooledReferralConnectorLDAPURLSecurityType enum for more information. By default, the CONDITIONALLY_USE_LDAP_AND_CONDITIONALLY_USE_START_TLS security type will be used.
      Returns:
      The type of communication security that the referral connector should use when creating connections for referral URLs with a scheme of "ldap".

    • getSSLSocketFactory

      @Nullable public SSLSocketFactory getSSLSocketFactory()
      Retrieves the SSL socket factory that will be used when performing TLS negotiation on any new connections created for the purpose of following referrals. By default, new pooled connections will use the same socket factory as the connection on which a referral was received.
      Returns:
      The SSL socket factory that will be used when performing TLS negotiation on any new connections created for the purpose of following referrals, or null if new pooled connections will use the same socket factory as the connection on which a referral was received.

    • close

      public void close()
      Closes and discards all connection pools that are associated with this connector. The connector will be unusable after it is closed.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • getReferralInterface

      @NotNull public LDAPConnectionPool getReferralInterface(@NotNull LDAPURL referralURL, @NotNull LDAPConnection connection) throws LDAPException
      Retrieves a FullLDAPInterface for use in following a referral returned in the provided result. The caller must not do anything to attempt to leave the interface in an unusable state (e.g., closing a connection or connection pool).
      Specified by:
      getReferralInterface in interface ReusableReferralConnector
      Parameters:
      referralURL - The LDAP URL for the referral to follow. It must not be null.
      connection - The connection on which the referral was received. It will not be null.
      Returns:
      A FullLDAPInterface for use in following a referral with the given URL.
      Throws:
      LDAPException - If a problem occurs while obtaining the FullLDAPInterface to use for following the referral.

    • getReferralConnection

      @NotNull public LDAPConnection getReferralConnection(@NotNull LDAPURL referralURL, @NotNull LDAPConnection connection) throws LDAPException
      Retrieves an (optionally authenticated) LDAP connection for use in following a referral as defined in the provided LDAP URL. The connection will automatically be closed after the referral has been followed.
      Specified by:
      getReferralConnection in interface ReferralConnector
      Parameters:
      referralURL - The LDAP URL representing the referral being followed.
      connection - The connection on which the referral was received.
      Returns:
      An LDAP connection established and optionally authenticated to the target system that may be used to attempt to follow a referral.
      Throws:
      LDAPException - If a problem occurs while establishing the connection or performing authentication on it. If an exception is thrown, then any underlying connection should be terminated before the exception is thrown.