Package com.unboundid.ldap.sdk

Class ServerSet

java.lang.Object
com.unboundid.ldap.sdk.ServerSet
Direct Known Subclasses:
DNSSRVRecordServerSet, FailoverServerSet, FastestConnectServerSet, FewestConnectionsServerSet, RoundRobinDNSServerSet, RoundRobinServerSet, SingleServerSet
@Extensible @ThreadSafety(level=INTERFACE_THREADSAFE) public abstract class ServerSet extends Object
This class defines an API that can be used to select between multiple directory servers when establishing a connection. Implementations are free to use any kind of logic that they desire when selecting the server to which the connection is to be established. They may also support the use of health checks to determine whether the created connections are suitable for use.

Implementations MUST be threadsafe to allow for multiple concurrent attempts to establish new connections.

  • Constructor Details

    • ServerSet

      protected ServerSet()
      Creates a new instance of this server set.

  • Method Details

    • includesAuthentication

      public boolean includesAuthentication()
      Indicates whether connections created by this server set will be authenticated.
      Returns:
      true if connections created by this server set will be authenticated, or false if not.

    • includesPostConnectProcessing

      public boolean includesPostConnectProcessing()
      Indicates whether connections created by this server set will have post-connect processing performed.
      Returns:
      true if connections created by this server set will have post-connect processing performed, or false if not.

    • getConnection

      @NotNull public abstract LDAPConnection getConnection() throws LDAPException
      Attempts to establish a connection to one of the directory servers in this server set. The connection that is returned must be established. The includesAuthentication() must return true if and only if the connection will also be authenticated, and the includesPostConnectProcessing() method must return true if and only if pre-authentication and post-authentication post-connect processing will have been performed. The caller may determine the server to which the connection is established using the LDAPConnection.getConnectedAddress() and LDAPConnection.getConnectedPort() methods.
      Returns:
      An LDAPConnection object that is established to one of the servers in this server set.
      Throws:
      LDAPException - If it is not possible to establish a connection to any of the servers in this server set.

    • getConnection

      @NotNull public LDAPConnection getConnection(@Nullable LDAPConnectionPoolHealthCheck healthCheck) throws LDAPException
      Attempts to establish a connection to one of the directory servers in this server set, using the provided health check to further validate the connection. The connection that is returned must be established. The includesAuthentication() must return true if and only if the connection will also be authenticated, and the includesPostConnectProcessing() method must return true if and only if pre-authentication and post-authentication post-connect processing will have been performed. The caller may determine the server to which the connection is established using the LDAPConnection.getConnectedAddress() and LDAPConnection.getConnectedPort() methods.
      Parameters:
      healthCheck - The health check to use to verify the health of the newly-created connection. It may be null if no additional health check should be performed. If it is non-null and this server set performs authentication, then the health check's ensureConnectionValidAfterAuthentication method will be invoked immediately after the bind operation is processed (regardless of whether the bind was successful or not). And regardless of whether this server set performs authentication, the health check's ensureNewConnectionValid method must be invoked on the connection to ensure that it is valid immediately before it is returned.
      Returns:
      An LDAPConnection object that is established to one of the servers in this server set.
      Throws:
      LDAPException - If it is not possible to establish a connection to any of the servers in this server set.

    • doBindPostConnectAndHealthCheckProcessing

      protected static void doBindPostConnectAndHealthCheckProcessing(@NotNull LDAPConnection connection, @Nullable BindRequest bindRequest, @Nullable PostConnectProcessor postConnectProcessor, @Nullable LDAPConnectionPoolHealthCheck healthCheck) throws LDAPException
      Performs the appropriate bind, post-connect, and health check processing for the provided connection, in the provided order. The processing performed will include:
      1. If the provided postConnectProcessor is not null, then invoke its processPreAuthenticatedConnection method on the provided connection. If this method throws an LDAPException, then it will propagated up to the caller of this method.
      2. If the provided bindRequest is not null, then authenticate the connection using that request. If the provided healthCheck is also not null, then invoke its ensureConnectionValidAfterAuthentication method on the connection, even if the bind was not successful. If the health check throws an LDAPException, then it will be propagated up to the caller of this method. If there is no health check or if it did not throw an exception but the bind attempt did throw an exception, then propagate that exception instead.
      3. If the provided postConnectProcessor is not null, then invoke its processPostAuthenticatedConnection method on the provided connection. If this method throws an LDAPException, then it will propagated up to the caller of this method.
      4. If the provided healthCheck is not null, then invoke its ensureNewConnectionValid method on the provided connection. If this method throws an LDAPException, then it will be propagated up to the caller of this method.
      Parameters:
      connection - The connection to be processed. It must not be null, and it must be established. Note that if an LDAPException is thrown by this method or anything that it calls, then the connection will have been closed before that exception has been propagated up to the caller of this method.
      bindRequest - The bind request to use to authenticate the connection. It may be null if no authentication should be performed.
      postConnectProcessor - The post-connect processor to invoke on the provided connection. It may be null if no post-connect processing should be performed.
      healthCheck - The health check to use to verify the health of connection. It may be null if no health check processing should be performed.
      Throws:
      LDAPException - If a problem is encountered during any of the processing performed by this method. If an exception is thrown, then the provided connection will have been closed.

    • associateConnectionWithThisServerSet

      protected final void associateConnectionWithThisServerSet(@NotNull LDAPConnection connection)
      Updates the provided connection to indicate that it was created by this server set.
      Parameters:
      connection - The connection to be updated to indicate it was created by this server set.

    • handleConnectionClosed

      protected void handleConnectionClosed(@NotNull LDAPConnection connection, @NotNull String host, int port, @NotNull DisconnectType disconnectType, @Nullable String message, @Nullable Throwable cause)
      Performs any processing that may be required when the provided connection is closed. This will only be invoked for connections created by this server set, and only if the associateConnectionWithThisServerSet(com.unboundid.ldap.sdk.LDAPConnection) method was called on the connection when it was created by this server set.
      Parameters:
      connection - The connection that has been closed.
      host - The address of the server to which the connection had been established.
      port - The port of the server to which the connection had been established.
      disconnectType - The disconnect type, which provides general information about the nature of the disconnect.
      message - A message that may be associated with the disconnect. It may be null if no message is available.
      cause - A Throwable that was caught and triggered the disconnect. It may be null if the disconnect was not triggered by a client-side exception or error.

    • shutDown

      public void shutDown()
      Shuts down this server set and frees any resources associated with it.

    • toString

      @NotNull public String toString()
      Retrieves a string representation of this server set.
      Overrides:
      toString in class Object
      Returns:
      A string representation of this server set.

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this server set to the provided buffer.
      Parameters:
      buffer - The buffer to which the string representation should be appended.