Package org.opends.server.api

Class ClientConnection

java.lang.Object
org.opends.server.api.ClientConnection
public abstract class ClientConnection extends Object
This class defines the set of methods and structures that must be implemented by a Directory Server client connection.

This class is deprecated, it should be replaced by ConnectionContext, see OPENDJ-3620

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    ClientConnection.AuthenticatedUsers
    This class provides a data structure which maps an authenticated user DN to the set of client connections authenticated as that user.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    ClientConnection(ServerContext serverContext)
    Performs the appropriate initialization generic to all client connections.
    protected
    ClientConnection(ServerContext serverContext, AuthenticationInfo authenticationInfo)
    Performs the appropriate initialization generic to all client connections.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cancelAllRequestsExcept(int msgId, LocalizableMessage reason)
    Attempts to cancel all active requests except for the request having the specified message ID, blocking until all of the requests are cancelled or completed.
    Result
    cancelRequest(int msgId, boolean notifyClient, LocalizableMessage reason)
    Attempts to cancel the request having the specified message ID, blocking until either the targeted request is cancelled or completed.
    final void
    deregisterPersistentSearch(PersistentSearch persistentSearch)
    Deregisters the provided persistent search for this client.
    abstract void
    disconnect(DisconnectReason disconnectReason, boolean sendNotification, LocalizableMessage message)
    Asynchronously closes the connection to the client, optionally sending it a message indicating the reason for the closure.
    final AuthenticationInfo
    getAuthenticationInfo()
    Retrieves information about the authentication that has been performed for this connection.
    abstract String
    getClientAddress()
    Returns a string representation of the address of the client.
    Certificate[]
    getClientCertificateChain()
    Returns the certificate chain associated with a connection that has been secured using SSL, or an empty array if SSL is not enabled on this connection (or there are no certificates).
    final String
    getClientHostPort()
    Retrieves the address and port (if available) of the client system, separated by a colon.
    abstract int
    getClientPort()
    Retrieves the port number for this connection on the client system if available.
    abstract ConnectionHandler<?>
    getConnectionHandler()
    Returns the connection handler that accepted this client connection.
    abstract long
    getConnectionId()
    Returns the unique identifier that has been assigned to this connection.
    protected final String
    getConnectTimeString()
    Returns a string representation of the time that this connection was established.
    long
    getIdleTime()
    Returns the length of time in milliseconds that this client connection has been idle.
    abstract JsonValue
    getMonitorSummary()
    Returns a summary of this client connection in JSON (format that is both human readable and machine parseable).
    final List<PersistentSearch>
    getPersistentSearches()
    Returns the persistent searches registered for this client.
    abstract String
    getProtocol()
    Returns the protocol that the client is using to communicate with the Directory Server.
    abstract InetAddress
    getRemoteAddress()
    Returns the InetAddress associated with the remote client system. It may be null if the client is not connected over an IP-based connection.
    final Object
    getSaslAuthStateInfo()
    Returns an opaque set of information that may be used for processing multi-stage SASL binds.
    abstract String
    getServerAddress()
    Returns a string representation of the address on the server to which the client connected.
    protected final ServerContext
    getServerContext()
    Returns the server context.
    final String
    getServerHostPort()
    Returns the address and port of the server system, separated by a colon.
    abstract int
    getServerPort()
    Retrieves the port number for this connection on the server system if available.
    abstract int
    getSsf()
    Return the Security Strength Factor of a client connection.
    String
    getTlsCipher()
    Return the TLS cipher suite of a client connection.
    String
    getTlsProtocol()
    Return the TLS protocol of a client connection.
    final boolean
    hasAllPrivileges(Privilege[] privileges, Operation operation)
    Indicates whether the authenticate client has all of the specified privileges.
    static boolean
    hasPrivilege(Entry authorizationEntry, Privilege privilege, ServerContext serverContext)
    Indicate whether the specified authorization entry parameter has the specified privilege.
    final boolean
    hasPrivilege(Privilege privilege, Operation operation)
    Indicates whether the authenticated client has the specified privilege.
    boolean
    isAdministrative()
    Indicates if this connection is on the Administration Connector which may mean it is excluded from certain checks.
    abstract @com.forgerock.opendj.util.LoomTODO({"HTTP specific - can be removed?"}) boolean
    isConnectionValid()
    Returns whether the Directory Server believes this connection to be valid and available for communication.
    abstract boolean
    isSecure()
    Indicates whether this client connection is currently using a secure mechanism to communicate with the server.
    boolean
    isStartTlsSupported()
    Returns true if this connection supports the start TLS request.
    final boolean
    mustChangePassword()
    Indicates whether the user associated with this client connection must change their password before they will be allowed to do anything else.
    boolean
    mustLogTlsHandshake()
    Returns whether TLS information must be logged by the caller.
    final void
    registerPersistentSearch(PersistentSearch persistentSearch)
    Registers the provided persistent search for this client.
    void
    setAuthenticationInfo(AuthenticationInfo authenticationInfo)
    Specifies information about the authentication that has been performed for this connection.
    final void
    setMustChangePassword(boolean mustChangePassword)
    Specifies whether the user associated with this client connection must change their password before they will be allowed to do anything else.
    final void
    setSaslAuthStateInfo(Object saslAuthState)
    Specifies an opaque set of information that may be used for processing multi-stage SASL binds.
    abstract String
    toString()
    Returns a string representation of this client connection.
    protected static LdapException
    writeTimeLimitExceeded(Duration timeout)
    Returns a new LdapException for max blocked write time limit exceeded.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • ClientConnection

      protected ClientConnection(ServerContext serverContext)
      Performs the appropriate initialization generic to all client connections.
      Parameters:
      serverContext - the server context

    • ClientConnection

      protected ClientConnection(ServerContext serverContext, AuthenticationInfo authenticationInfo)
      Performs the appropriate initialization generic to all client connections.
      Parameters:
      serverContext - the server context
      authenticationInfo - the initial authentication info

  • Method Details

    • getConnectTimeString

      protected final String getConnectTimeString()
      Returns a string representation of the time that this connection was established.
      Returns:
      a string representation of the time that this connection was established

    • getConnectionId

      public abstract long getConnectionId()
      Returns the unique identifier that has been assigned to this connection.
      Returns:
      the unique identifier that has been assigned to this connection

    • getConnectionHandler

      public abstract ConnectionHandler<?> getConnectionHandler()
      Returns the connection handler that accepted this client connection.
      Returns:
      the connection handler that accepted this client connection

    • getProtocol

      public abstract String getProtocol()
      Returns the protocol that the client is using to communicate with the Directory Server.
      Returns:
      the protocol that the client is using to communicate with the Directory Server

    • getClientAddress

      public abstract String getClientAddress()
      Returns a string representation of the address of the client.
      Returns:
      a string representation of the address of the client

    • getClientPort

      public abstract int getClientPort()
      Retrieves the port number for this connection on the client system if available.
      Returns:
      The port number for this connection on the client system or -1 if there is no client port associated with this connection (e.g. internal client).

    • getClientHostPort

      public final String getClientHostPort()
      Retrieves the address and port (if available) of the client system, separated by a colon.
      Returns:
      The address and port of the client system, separated by a colon.

    • getServerAddress

      public abstract String getServerAddress()
      Returns a string representation of the address on the server to which the client connected.
      Returns:
      a string representation of the address on the server to which the client connected

    • getServerPort

      public abstract int getServerPort()
      Retrieves the port number for this connection on the server system if available.
      Returns:
      The port number for this connection on the server system or -1 if there is no server port associated with this connection (e.g. internal client).

    • getServerHostPort

      public final String getServerHostPort()
      Returns the address and port of the server system, separated by a colon.
      Returns:
      the address and port of the server system, separated by a colon

    • getRemoteAddress

      public abstract InetAddress getRemoteAddress()
      Returns the InetAddress associated with the remote client system. It may be null if the client is not connected over an IP-based connection.
      Returns:
      the InetAddress associated with the remote client system. It may be null if the client is not connected over an IP-based connection

    • isAdministrative

      public boolean isAdministrative()
      Indicates if this connection is on the Administration Connector which may mean it is excluded from certain checks.
      Returns:
      true if this connection is on the Administration Connector.

    • isConnectionValid

      public abstract @com.forgerock.opendj.util.LoomTODO({"HTTP specific - can be removed?"}) boolean isConnectionValid()
      Returns whether the Directory Server believes this connection to be valid and available for communication.
      Returns:
      true if the connection is valid, false otherwise

    • isStartTlsSupported

      public boolean isStartTlsSupported()
      Returns true if this connection supports the start TLS request.
      Returns:
      true if this connection supports the start TLS request

    • isSecure

      public abstract boolean isSecure()
      Indicates whether this client connection is currently using a secure mechanism to communicate with the server. Note that this may change over time based on operations performed by the client or server (e.g., it may go from false to true if the client uses the StartTLS extended operation).
      Returns:
      true if the client connection is currently using a secure mechanism to communicate with the server, or false if not.

    • getClientCertificateChain

      public Certificate[] getClientCertificateChain()
      Returns the certificate chain associated with a connection that has been secured using SSL, or an empty array if SSL is not enabled on this connection (or there are no certificates).
      Returns:
      The array of certificates associated with this connection.

    • writeTimeLimitExceeded

      protected static LdapException writeTimeLimitExceeded(Duration timeout)
      Returns a new LdapException for max blocked write time limit exceeded.
      Parameters:
      timeout - the value for the timeout
      Returns:
      a new LdapException for max blocked write time limit exceeded

    • disconnect

      public abstract void disconnect(DisconnectReason disconnectReason, boolean sendNotification, LocalizableMessage message)
      Asynchronously closes the connection to the client, optionally sending it a message indicating the reason for the closure. Note that the ability to send a notice of disconnection may not be available for all protocols or under all circumstances.

      All subclasses must invoke the finalizeConnectionInternal method during the course of processing this method. In addition, implementations should not block until active requests are cancelled due to the risk of deadlocks in cases where a request attempts to disconnect its own connection (e.g. when deleting the authenticated user).

      Parameters:
      disconnectReason - The disconnect reason that provides the generic cause for the disconnect.
      sendNotification - Indicates whether to try to provide notification to the client that the connection will be closed.
      message - The message to send to the client. It may be null if no notification is to be sent.

    • mustChangePassword

      public final boolean mustChangePassword()
      Indicates whether the user associated with this client connection must change their password before they will be allowed to do anything else.
      Returns:
      true if the user associated with this client connection must change their password before they will be allowed to do anything else, or false if not.

    • setMustChangePassword

      public final void setMustChangePassword(boolean mustChangePassword)
      Specifies whether the user associated with this client connection must change their password before they will be allowed to do anything else.
      Parameters:
      mustChangePassword - Specifies whether the user associated with this client connection must change their password before they will be allowed to do anything else.

    • getPersistentSearches

      public final List<PersistentSearch> getPersistentSearches()
      Returns the persistent searches registered for this client.
      Returns:
      the persistent searches registered for this client

    • registerPersistentSearch

      public final void registerPersistentSearch(PersistentSearch persistentSearch)
      Registers the provided persistent search for this client. Note that this should only be called by DirectoryServer.registerPersistentSearch and not through any other means.
      Parameters:
      persistentSearch - The persistent search to register for this client.

    • deregisterPersistentSearch

      public final void deregisterPersistentSearch(PersistentSearch persistentSearch)
      Deregisters the provided persistent search for this client. Note that this should only be called by DirectoryServer.deregisterPersistentSearch and not through any other means.
      Parameters:
      persistentSearch - The persistent search to deregister for this client.

    • getAuthenticationInfo

      public final AuthenticationInfo getAuthenticationInfo()
      Retrieves information about the authentication that has been performed for this connection.
      Returns:
      Information about the user that is currently authenticated on this connection.

    • setAuthenticationInfo

      public void setAuthenticationInfo(AuthenticationInfo authenticationInfo)
      Specifies information about the authentication that has been performed for this connection.
      Parameters:
      authenticationInfo - Information about the authentication that has been performed for this connection

    • hasPrivilege

      public static boolean hasPrivilege(Entry authorizationEntry, Privilege privilege, ServerContext serverContext)
      Indicate whether the specified authorization entry parameter has the specified privilege. The method can be used to perform a "what-if" scenario.
      Parameters:
      authorizationEntry - The authentication entry to use.
      privilege - The privilege to check for.
      serverContext - The server context
      Returns:
      true if the authentication entry has the specified privilege, or false if not.

    • hasPrivilege

      public final boolean hasPrivilege(Privilege privilege, Operation operation)
      Indicates whether the authenticated client has the specified privilege.
      Parameters:
      privilege - The privilege for which to make the determination.
      operation - The operation being processed which needs to make the privilege determination, or null if there is no associated operation.
      Returns:
      true if the authenticated client has the specified privilege, or false if not.

    • hasAllPrivileges

      public final boolean hasAllPrivileges(Privilege[] privileges, Operation operation)
      Indicates whether the authenticate client has all of the specified privileges.
      Parameters:
      privileges - The array of privileges for which to make the determination.
      operation - The operation being processed which needs to make the privilege determination, or null if there is no associated operation.
      Returns:
      true if the authenticated client has all of the specified privileges, or false if not.

    • getSaslAuthStateInfo

      public final Object getSaslAuthStateInfo()
      Returns an opaque set of information that may be used for processing multi-stage SASL binds.
      Returns:
      an opaque set of information that may be used for processing multi-stage SASL binds

    • setSaslAuthStateInfo

      public final void setSaslAuthStateInfo(Object saslAuthState)
      Specifies an opaque set of information that may be used for processing multi-stage SASL binds.
      Parameters:
      saslAuthState - An opaque set of information that may be used for processing multi-stage SASL binds.

    • getServerContext

      protected final ServerContext getServerContext()
      Returns the server context.
      Returns:
      the server context

    • getMonitorSummary

      public abstract JsonValue getMonitorSummary()
      Returns a summary of this client connection in JSON (format that is both human readable and machine parseable).
      Returns:
      A summary of this client connection in JSON.

    • toString

      public abstract String toString()
      Returns a string representation of this client connection.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this client connection

    • getIdleTime

      public long getIdleTime()
      Returns the length of time in milliseconds that this client connection has been idle.

      Note that the default implementation will always return zero. Subclasses associated with connection handlers should override this method if they wish to provided idle time limit functionality.

      Returns:
      the length of time in milliseconds that this client connection has been idle

    • getSsf

      public abstract int getSsf()
      Return the Security Strength Factor of a client connection.
      Returns:
      An integer representing the SSF value of a connection.

    • getTlsProtocol

      public String getTlsProtocol()
      Return the TLS protocol of a client connection.
      Returns:
      A string, or "NONE" if TLS handshake is not complete, or null if TLS is not active.

    • getTlsCipher

      public String getTlsCipher()
      Return the TLS cipher suite of a client connection.
      Returns:
      A cipher name, or "SSL_NULL_WITH_NULL_NULL" if TLS handshake is not complete, or null if TLS is not active.

    • mustLogTlsHandshake

      public boolean mustLogTlsHandshake()
      Returns whether TLS information must be logged by the caller. This method relies on side-effects to ensure the TLS information is logged only once per connection, even in the face of concurrent requests.
      Returns:
      whether TLS information must be logged by the caller

    • cancelRequest

      public Result cancelRequest(int msgId, boolean notifyClient, LocalizableMessage reason)
      Attempts to cancel the request having the specified message ID, blocking until either the targeted request is cancelled or completed.
      Parameters:
      msgId - The message ID of the request to be cancelled.
      notifyClient - true if the client should receive a response if the request was successfully cancelled.
      reason - A message explaining the reason for the cancellation.
      Returns:
      The result of the cancellation request.

    • cancelAllRequestsExcept

      public void cancelAllRequestsExcept(int msgId, LocalizableMessage reason)
      Attempts to cancel all active requests except for the request having the specified message ID, blocking until all of the requests are cancelled or completed.
      Parameters:
      msgId - The message ID of the request that should not be cancelled.
      reason - A message explaining the reason for the cancellation.