Package org.opends.server.api

Class ClientConnection

    • Constructor Summary

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

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void deregisterPersistentSearch​(PersistentSearch persistentSearch)
      Deregisters the provided persistent search for this client.
      abstract void disconnect​(DisconnectReason disconnectReason, boolean sendNotification, LocalizableMessage message)
      Closes the connection to the client, optionally sending it a message indicating the reason for the closure.
      protected void finalizeConnectionInternal()
      Performs any internal cleanup that may be necessary when this client connection is disconnected.
      void finishBind()
      Indicates a bind or start TLS request processing is finished and the client connection may start processing data read from the socket again.
      void finishSaslBind()
      Indicates a multistage SASL bind operation is finished and the client connection may accept additional LDAP messages.
      void finishStartTLS()
      Indicates a bind or start TLS request processing is finished and the client connection may start processing data read from the socket again.
      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.
      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 long getConnectionID()
      Retrieves the unique identifier that has been assigned to this connection.
      protected String getConnectTimeString()
      Retrieves a string representation of the time that this connection was established.
      long getIdleTime()
      Retrieves the length of time in milliseconds that this client connection has been idle.
      long getIdleTimeLimit()
      Retrieves the maximum length of time in milliseconds that this client connection will be allowed to remain idle before it should be disconnected.
      Dn getKeyManagerProviderDN()
      Retrieves the DN of the key manager provider that should be used for operations requiring access to a key manager.
      long getMaxBlockedWriteTimeLimit()
      Retrieves the maximum length of time in milliseconds that attempts to write data to the client should be allowed to block.
      int getMaxCandidateSetSize()
      Retrieves the default maximum number of entry IDs the server may retrieve while cursoring through an index during a search.
      abstract JsonValue getMonitorSummary()
      Returns a summary of this client connection in JSON (format that is both human readable and machine parseable).
      abstract Operation getOperationInProgress​(int messageID)
      Retrieves the operation in progress with the specified message ID.
      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.
      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 ServerContext getServerContext()
      Returns the server context.
      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.
      int getSizeLimit()
      Retrieves the size limit that will be enforced for searches performed using this client connection.
      abstract int getSSF()
      Return the Security Strength Factor of a client connection.
      int getTimeLimit()
      Retrieves the time limit that will be enforced for searches performed using this client connection.
      String getTlsCipher()
      Return the TLS cipher suite of a client connection.
      String getTlsProtocol()
      Return the TLS protocol of a client connection.
      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.
      boolean hasPrivilege​(Privilege privilege, Operation operation)
      Indicates whether the authenticated client has the specified privilege.
      abstract boolean isConnectionValid()
      Returns whether the Directory Server believes this connection to be valid and available for communication.
      boolean isInnerConnection()
      Returns whether this connection is used for inner work not directly requested by an external client.
      abstract boolean isSecure()
      Indicates whether this client connection is currently using a secure mechanism to communicate with the server.
      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.
      void registerPersistentSearch​(PersistentSearch persistentSearch)
      Registers the provided persistent search for this client.
      abstract void removeOperationInProgress​(int messageID)
      Removes the provided operation from the set of operations in progress for this client connection.
      protected abstract boolean sendIntermediateResponseMessage​(Operation operation, IntermediateResponse intermediateResponse)
      Sends the provided intermediate response message to the client.
      void sendResponse​(Operation operation)
      Removes the provided operation from the set of operations in progress of this client connection and sends a response to the client based on the information in the provided operation.
      protected void sendResponse​(Operation operation, int ldapVersion, SslOptions startTlsOptions)
      Removes the provided operation from the set of operations in progress of this client connection and sends a response to the client based on the information in the provided operation.
      abstract void sendSearchEntry​(SearchOperation searchOperation, SearchResultEntry searchEntry)
      Sends the provided search result entry to the client.
      abstract boolean sendSearchReference​(SearchOperation searchOperation, SearchResultReference searchReference)
      Sends the provided search result reference to the client.
      void setAuthenticationInfo​(AuthenticationInfo authenticationInfo)
      Specifies information about the authentication that has been performed for this connection.
      void setIdleTimeLimit​(long idleTimeLimitMs)
      Specifies the maximum length of time in milliseconds that this client connection will be allowed to remain idle before it should be disconnected.
      void setMaxCandidateSetSize​(int maxCandidateSetSize)
      Specifies the default maximum number of entry IDs the server may retrieve while cursoring through an index during a search.
      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.
      void setResourceLimits​(Entry userEntry)
      Set the resource limits from the specified user entry.
      void setSASLAuthStateInfo​(Object saslAuthState)
      Specifies an opaque set of information that may be used for processing multi-stage SASL binds.
      void setSizeLimit​(int sizeLimit)
      Specifies the size limit that will be enforced for searches performed using this client connection.
      void setTimeLimit​(int timeLimitSec)
      Specifies the time limit that will be enforced for searches performed using this client connection.
      void setUnauthenticated()
      Sets properties in this client connection to indicate that the client is unauthenticated.
      String toString()
      Retrieves a string representation of this client connection.
      abstract void toString​(StringBuilder buffer)
      Appends a string representation of this client connection to the provided buffer.
      void updateAuthenticationInfo​(Entry oldEntry, Entry newEntry)
      Updates the cached entry associated with either the authentication and/or authorization identity with the provided version.
      protected void updatePrivileges​(Entry entry)
      Updates the privileges associated with this client connection object based on the provided entry for the authentication identity.
      protected static LdapException writeTimeLimitExceeded​(Duration timeout)
      Returns a new LdapException for max blocked write time limit exceeded.

    • Field Detail

      • authenticationInfo

        protected AuthenticationInfo authenticationInfo
        The set of authentication information for this client connection.

      • saslBindInProgress

        protected final AtomicBoolean saslBindInProgress
        Indicates whether a multistage SASL bind is currently in progress on this client connection. If so, then no other operations should be allowed until the bind completes.

      • bindInProgress

        protected final AtomicBoolean bindInProgress
        Indicates if a bind request is currently in progress on this client connection. If so, then no further socket reads will occur until the request completes.

      • startTLSInProgress

        protected final AtomicBoolean startTLSInProgress
        Indicates if a Start TLS request is currently in progress on this client connection. If so, then no further socket reads will occur until the request completes.

    • Constructor Detail

      • ClientConnection

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

    • Method Detail

      • finalizeConnectionInternal

        @PublicAPI(stability=PRIVATE,
           mayInvoke=true,
           notes="This method should only be invoked by connection handlers.")
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 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 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

      • 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.

      • getMaxBlockedWriteTimeLimit

        public long getMaxBlockedWriteTimeLimit()
        Retrieves the maximum length of time in milliseconds that attempts to write data to the client should be allowed to block.
        Returns:
        The maximum length of time in milliseconds that attempts to write data to the client should be allowed to block.

      • 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

      • sendResponse

        public void sendResponse​(Operation operation)
        Removes the provided operation from the set of operations in progress of this client connection and sends a response to the client based on the information in the provided operation.

        Note that this does not make any attempt to cancel any processing that may already be in progress for the operation.

        Parameters:
        operation - The operation for which to send the response

      • sendResponse

        protected void sendResponse​(Operation operation,
                            int ldapVersion,
                            SslOptions startTlsOptions)
        Removes the provided operation from the set of operations in progress of this client connection and sends a response to the client based on the information in the provided operation.

        Note that this does not make any attempt to cancel any processing that may already be in progress for the operation.

        Parameters:
        operation - The operation for which to send the response
        ldapVersion - The ldap protocol version
        startTlsOptions - The options for StartTLS
        See Also:
        sendResponse(Operation)

      • sendSearchEntry

        public abstract void sendSearchEntry​(SearchOperation searchOperation,
                                     SearchResultEntry searchEntry)
        Sends the provided search result entry to the client.
        Parameters:
        searchOperation - The search operation with which the entry is associated.
        searchEntry - The search result entry to be sent to the client.

      • sendSearchReference

        public abstract boolean sendSearchReference​(SearchOperation searchOperation,
                                            SearchResultReference searchReference)
        Sends the provided search result reference to the client.
        Parameters:
        searchOperation - The search operation with which the reference is associated.
        searchReference - The search result reference to be sent to the client.
        Returns:
        true if the client is able to accept referrals, or false if the client cannot handle referrals and no more attempts should be made to send them for the associated search operation.

      • sendIntermediateResponseMessage

        protected abstract boolean sendIntermediateResponseMessage​(Operation operation,
                                                           IntermediateResponse intermediateResponse)
        Sends the provided intermediate response message to the client.
        Parameters:
        operation - The operation with which the intermediate response is associated.
        intermediateResponse - The intermediate response message to be sent.
        Returns:
        true if processing on the associated operation should continue, or false if not.

      • disconnect

        public abstract void disconnect​(DisconnectReason disconnectReason,
                                boolean sendNotification,
                                LocalizableMessage message)
        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. Also note that when attempting to disconnect a client connection as a part of operation processing (e.g., within a plugin or other extension), the disconnectClient method within that operation should be called rather than invoking this method directly.

        All subclasses must invoke the finalizeConnectionInternal method during the course of processing this method.

        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.

      • getOperationInProgress

        public abstract Operation getOperationInProgress​(int messageID)
        Retrieves the operation in progress with the specified message ID.
        Parameters:
        messageID - The message ID of the operation to retrieve.
        Returns:
        The operation in progress with the specified message ID, or null if no such operation could be found.

      • removeOperationInProgress

        public abstract void removeOperationInProgress​(int messageID)
        Removes the provided operation from the set of operations in progress for this client connection. Note that this does not make any attempt to cancel any processing that may already be in progress for the operation.
        Parameters:
        messageID - The message ID of the operation to remove from the set of operations in progress.

      • 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

        @PublicAPI(stability=PRIVATE)
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

        @PublicAPI(stability=PRIVATE)
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 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. It should not be null.

      • 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.

      • setUnauthenticated

        public void setUnauthenticated()
        Sets properties in this client connection to indicate that the client is unauthenticated. This includes setting the authentication info structure to an empty default, as well as setting the size and time limit values to their defaults.

      • 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 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 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.

      • updatePrivileges

        protected final void updatePrivileges​(Entry entry)
        Updates the privileges associated with this client connection object based on the provided entry for the authentication identity.
        Parameters:
        entry - The entry for the authentication identity associated with this client connection.

      • 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 ServerContext getServerContext()
        Returns the server context.
        Returns:
        the server context

      • getSizeLimit

        public final int getSizeLimit()
        Retrieves the size limit that will be enforced for searches performed using this client connection.
        Returns:
        The size limit that will be enforced for searches performed using this client connection.

      • setSizeLimit

        public void setSizeLimit​(int sizeLimit)
        Specifies the size limit that will be enforced for searches performed using this client connection.
        Parameters:
        sizeLimit - The size limit that will be enforced for searches performed using this client connection.

      • getIdleTimeLimit

        public final long getIdleTimeLimit()
        Retrieves the maximum length of time in milliseconds that this client connection will be allowed to remain idle before it should be disconnected.
        Returns:
        The maximum length of time in milliseconds that this client connection will be allowed to remain idle before it should be disconnected.

      • setIdleTimeLimit

        public void setIdleTimeLimit​(long idleTimeLimitMs)
        Specifies the maximum length of time in milliseconds that this client connection will be allowed to remain idle before it should be disconnected.
        Parameters:
        idleTimeLimitMs - The maximum length of time in milliseconds that this client connection will be allowed to remain idle before it should be disconnected.

      • getMaxCandidateSetSize

        public int getMaxCandidateSetSize()
        Retrieves the default maximum number of entry IDs the server may retrieve while cursoring through an index during a search.
        Returns:
        The default maximum number of entry IDs the server may retrieve while cursoring through an index during a search.

      • setMaxCandidateSetSize

        public void setMaxCandidateSetSize​(int maxCandidateSetSize)
        Specifies the default maximum number of entry IDs the server may retrieve while cursoring through an index during a search.
        Parameters:
        maxCandidateSetSize - The default maximum number of entry IDs the server may retrieve while cursoring through an index during a search.

      • getTimeLimit

        public final int getTimeLimit()
        Retrieves the time limit that will be enforced for searches performed using this client connection.
        Returns:
        The time limit that will be enforced for searches performed using this client connection.

      • setTimeLimit

        public void setTimeLimit​(int timeLimitSec)
        Specifies the time limit that will be enforced for searches performed using this client connection.
        Parameters:
        timeLimitSec - The time limit that will be enforced for searches performed using this client connection.

      • setResourceLimits

        public void setResourceLimits​(Entry userEntry)
        Set the resource limits from the specified user entry.

        Note code is duplicated from org.opends.server.core.BindOperation.setResourceLimits(Entry).

        Parameters:
        userEntry - The user's entry which may contain resource limits

      • 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.

      • getKeyManagerProviderDN

        public Dn getKeyManagerProviderDN()
        Retrieves the DN of the key manager provider that should be used for operations requiring access to a key manager. The default implementation returns null to indicate that no key manager provider is available, but subclasses should override this method to return a valid DN if they perform operations which may need access to a key manager.
        Returns:
        The DN of the key manager provider that should be used for operations requiring access to a key manager, or null if there is no key manager provider configured for this client connection.

      • 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

        public 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 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 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

      • finishBind

        public void finishBind()
        Indicates a bind or start TLS request processing is finished and the client connection may start processing data read from the socket again. This must be called after processing each bind request in a multistage SASL bind.

      • finishStartTLS

        public void finishStartTLS()
        Indicates a bind or start TLS request processing is finished and the client connection may start processing data read from the socket again. This must be called after processing each bind request in a multistage SASL bind.

      • finishSaslBind

        public void finishSaslBind()
        Indicates a multistage SASL bind operation is finished and the client connection may accept additional LDAP messages.

      • isInnerConnection

        public boolean isInnerConnection()
        Returns whether this connection is used for inner work not directly requested by an external client.
        Returns:
        true if this is an inner connection, false otherwise