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 java.lang.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 Summary
Constructors Modifier Constructor Description protected
ServerSet()
Creates a new instance of this server set.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected void
associateConnectionWithThisServerSet(LDAPConnection connection)
Updates the provided connection to indicate that it was created by this server set.protected static void
doBindPostConnectAndHealthCheckProcessing(LDAPConnection connection, BindRequest bindRequest, PostConnectProcessor postConnectProcessor, LDAPConnectionPoolHealthCheck healthCheck)
Performs the appropriate bind, post-connect, and health check processing for the provided connection, in the provided order.abstract LDAPConnection
getConnection()
Attempts to establish a connection to one of the directory servers in this server set.LDAPConnection
getConnection(LDAPConnectionPoolHealthCheck healthCheck)
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.protected void
handleConnectionClosed(LDAPConnection connection, java.lang.String host, int port, DisconnectType disconnectType, java.lang.String message, java.lang.Throwable cause)
Performs any processing that may be required when the provided connection is closed.boolean
includesAuthentication()
Indicates whether connections created by this server set will be authenticated.boolean
includesPostConnectProcessing()
Indicates whether connections created by this server set will have post-connect processing performed.void
shutDown()
Shuts down this server set and frees any resources associated with it.java.lang.String
toString()
Retrieves a string representation of this server set.void
toString(java.lang.StringBuilder buffer)
Appends a string representation of this server set to the provided buffer.
-
-
-
Constructor Detail
-
ServerSet
protected ServerSet()
Creates a new instance of this server set.
-
-
Method Detail
-
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, orfalse
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, orfalse
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. TheincludesAuthentication()
must return true if and only if the connection will also be authenticated, and theincludesPostConnectProcessing()
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 theLDAPConnection.getConnectedAddress()
andLDAPConnection.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. TheincludesAuthentication()
must return true if and only if the connection will also be authenticated, and theincludesPostConnectProcessing()
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 theLDAPConnection.getConnectedAddress()
andLDAPConnection.getConnectedPort()
methods.- Parameters:
healthCheck
- The health check to use to verify the health of the newly-created connection. It may benull
if no additional health check should be performed. If it is non-null
and this server set performs authentication, then the health check'sensureConnectionValidAfterAuthentication
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'sensureNewConnectionValid
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:-
If the provided
postConnectProcessor
is notnull
, then invoke itsprocessPreAuthenticatedConnection
method on the provided connection. If this method throws anLDAPException
, then it will propagated up to the caller of this method. -
If the provided
bindRequest
is notnull
, then authenticate the connection using that request. If the providedhealthCheck
is also notnull
, then invoke itsensureConnectionValidAfterAuthentication
method on the connection, even if the bind was not successful. If the health check throws anLDAPException
, 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. -
If the provided
postConnectProcessor
is notnull
, then invoke itsprocessPostAuthenticatedConnection
method on the provided connection. If this method throws anLDAPException
, then it will propagated up to the caller of this method. -
If the provided
healthCheck
is notnull
, then invoke itsensureNewConnectionValid
method on the provided connection. If this method throws anLDAPException
, then it will be propagated up to the caller of this method.
- Parameters:
connection
- The connection to be processed. It must not benull
, and it must be established. Note that if anLDAPException
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 benull
if no authentication should be performed.postConnectProcessor
- The post-connect processor to invoke on the provided connection. It may benull
if no post-connect processing should be performed.healthCheck
- The health check to use to verify the health of connection. It may benull
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.
-
If the provided
-
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 java.lang.String host, int port, @NotNull DisconnectType disconnectType, @Nullable java.lang.String message, @Nullable java.lang.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 theassociateConnectionWithThisServerSet(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 benull
if no message is available.cause
- AThrowable
that was caught and triggered the disconnect. It may benull
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 java.lang.String toString()
Retrieves a string representation of this server set.- Overrides:
toString
in classjava.lang.Object
- Returns:
- A string representation of this server set.
-
-