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

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    ClientConnection(ServerContext serverContext)
    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.
    protected static Result
    convertResult(Request request, Result result)
    Converts a result to a Result having the appropriate type for the given Request.
    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.
    protected final void
    finalizeConnectionInternal()
    Performs any internal cleanup that may be necessary when this client connection is disconnected.
    final AuthenticationInfo
    getAuthenticationInfo()
    Retrieves information about the authentication that has been performed for this connection.
    abstract String
    getClientAddress()
    Retrieves 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()
    Retrieves the connection handler that accepted this client connection.
    abstract @com.forgerock.opendj.util.LoomTODO({"Fix shouting"}) long
    getConnectionID()
    Retrieves the unique identifier that has been assigned to this connection.
    protected final String
    getConnectTimeString()
    Retrieves a string representation of the time that this connection was established.
    @com.forgerock.opendj.util.LoomTODO({"LDAP specific - can be removed"}) long
    getIdleTime()
    Retrieves 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()
    Retrieves the set of persistent searches registered for this client.
    abstract String
    getProtocol()
    Retrieves the protocol that the client is using to communicate with the Directory Server.
    abstract InetAddress
    getRemoteAddress()
    Retrieves the InetAddress associated with the remote client system.
    final Object
    getSASLAuthStateInfo()
    Retrieves an opaque set of information that may be used for processing multi-stage SASL binds.
    abstract String
    getServerAddress()
    Retrieves 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()
    Retrieves 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 @com.forgerock.opendj.util.LoomTODO({"Fix shouting"}) int
    getSSF()
    Return the Security Strength Factor of a client connection.
    protected String
    getThreadNameForRequest(RequestContext context, Request request)
    Returns the name that should be used for processing a request.
    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.
    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.
    protected final void
    setAuthenticationInfoNoTrackingOfAuthenticatedUsers(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.
    final String
    toString()
    Retrieves a string representation of this client connection.
    protected abstract void
    toString(StringBuilder buffer)
    Appends a string representation of this client connection to the provided buffer.
    final void
    updateAuthenticationInfo(Entry oldEntry, Entry newEntry)
    Updates the cached entry associated with either the authentication and/or authorization identity with the provided version.
    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

  • Method Details

    • finalizeConnectionInternal

      protected final void finalizeConnectionInternal()
      Performs any internal cleanup that may be necessary when this client connection is disconnected. In this case, it will be used to ensure that the connection is deregistered with the AuthenticatedUsers manager, and will then invoke the finalizeClientConnection method.

    • getConnectTimeString

      protected final String getConnectTimeString()
      Retrieves 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 @com.forgerock.opendj.util.LoomTODO({"Fix shouting"}) long getConnectionID()
      Retrieves 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()
      Retrieves the connection handler that accepted this client connection.
      Returns:
      The connection handler that accepted this client connection.

    • getProtocol

      public abstract String getProtocol()
      Retrieves 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()
      Retrieves 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()
      Retrieves 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()
      Retrieves 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()
      Retrieves the InetAddress associated with the remote client system.
      Returns:
      The InetAddress associated with the remote client system. It may be null if the client is not connected over an IP-based connection.

    • 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()
      Retrieves the set of persistent searches registered for this client.
      Returns:
      The set of 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

    • setAuthenticationInfoNoTrackingOfAuthenticatedUsers

      protected final void setAuthenticationInfoNoTrackingOfAuthenticatedUsers(AuthenticationInfo authenticationInfo)
      Specifies information about the authentication that has been performed for this connection. Contrary to setAuthenticationInfo(AuthenticationInfo), the current method does not track the authentication info in the authenticated users.
      Parameters:
      authenticationInfo - null-able information about the authentication that has been performed for this connection

    • updateAuthenticationInfo

      public final void updateAuthenticationInfo(Entry oldEntry, Entry newEntry)
      Updates the cached entry associated with either the authentication and/or authorization identity with the provided version.
      Parameters:
      oldEntry - The user entry currently serving as the authentication and/or authorization identity.
      newEntry - The updated entry that should replace the existing entry. It may optionally have a different DN than the old entry.

    • 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()
      Retrieves 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 final String toString()
      Retrieves a string representation of this client connection.
      Overrides:
      toString in class Object
      Returns:
      A string representation of this client connection.

    • toString

      protected abstract void toString(StringBuilder buffer)
      Appends a string representation of this client connection to the provided buffer.
      Parameters:
      buffer - The buffer to which the information should be appended.

    • getIdleTime

      public @com.forgerock.opendj.util.LoomTODO({"LDAP specific - can be removed"}) long getIdleTime()
      Retrieves 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 @com.forgerock.opendj.util.LoomTODO({"Fix shouting"}) 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.

    • convertResult

      protected static Result convertResult(Request request, Result result)
      Converts a result to a Result having the appropriate type for the given Request.
      Parameters:
      request - The request.
      result - The result.
      Returns:
      The converted result.

    • getThreadNameForRequest

      protected String getThreadNameForRequest(RequestContext context, Request request)
      Returns the name that should be used for processing a request.
      Parameters:
      context - The request context.
      request - The request.
      Returns:
      The name of the thread.