Package com.unboundid.directory.sdk.common.types

Interface ClientContext

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void disconnect​(DisconnectReason reason, boolean notifyClient, java.lang.String message)
      Terminates the connection to the client and interrupts any operations that may be in progress on that connection.
      java.lang.Object getAttachment​(java.lang.String name)
      Retrieves a named object that has been associated with this client connection.
      AuthInfo getAuthInfo()
      Retrieves information about the authentication state of the client connection.
      java.lang.String getClientConnectionPolicyDN()
      Retrieves the DN of the entry that defines the client connection policy to which the associated client connection is assigned.
      java.lang.String getClientConnectionPolicyName()
      Retrieves the name of the client connection policy to which the associated client connection is assigned.
      java.net.InetAddress getClientInetAddress()
      Retrieves an InetAddress representing the address of the client system, if available.
      long getConnectionID()
      Retrieves the identifier that has been assigned to the associated client connection.
      long getConnectTime()
      Retrieves the time that the connection was established.
      java.util.Map<DN,​Group> getGroups​(OperationContext operation, boolean directMembershipOnly)
      Retrieves the groups in which the currently-authenticated user is a member, indexed by group DN.
      InternalConnection getInternalConnection​(java.lang.String dn, boolean usePolicyFromConnection)
      Retrieves an internal connection that is authenticated as the specified user.
      InternalConnection getInternalRootConnection​(boolean usePolicyFromConnection)
      Retrieves an internal connection that is authenticated as a root user that is not subject to access control.
      InternalConnection getInternalUserConnection​(boolean usePolicyFromConnection)
      Retrieves an internal connection that is authenticated as the same user as the associated client connection.
      java.util.List<java.lang.String> getMatchedConnectionCriteria()
      Returns a List containing the names of all the Connection Criteria that match this connection.
      java.util.Set<java.lang.String> getPrivilegeNames()
      Retrieves the names of the privileges held by the currently-authenticated user.
      java.lang.String getProtocol()
      Retrieves the name of the protocol that the client is using to communicate with the server.
      java.lang.Object getSASLAuthStateInfo()
      Retrieves an opaque object with information about the state of an active multi-stage SASL bind.
      ServerContext getServerContext()
      Retrieves information about the server with which the client connection is associated.
      java.net.InetAddress getServerInetAddress()
      Retrieves an InetAddress representing the address on the server to which the client established the connection, if available.
      boolean hasPrivilege​(java.lang.String privilegeName, OperationContext operation)
      Indicates whether the currently-authenticated user has the specified privilege.
      boolean isAuthenticated()
      Indicates whether the client has authenticated to the server.
      boolean isInternal()
      Indicates whether this represents an internal client connection.
      boolean isMemberOf​(java.lang.String groupDN, OperationContext operation)
      Indicates whether the currently-authenticated user is a member of the specified group.
      boolean isSecure()
      Indicates whether the client is communicating with the server in a secure manner.
      boolean matchesConnectionCriteria​(java.lang.String criteriaName)
      Determines whether this ClientContext matches the given Connection Criteria.
      void sendUnsolicitedNotification​(java.lang.String oid, ResultCode resultCode, java.lang.String message)
      Attempts to send an unsolicited notification to the client with the provided information.
      java.lang.Object setAttachment​(java.lang.String name, java.lang.Object value)
      Attaches an object to this client connection.
      void setSASLAuthStateInfo​(java.lang.Object saslAuthStateInfo)
      Sets state information for an active multi-stage SASL bind.
      java.lang.String toString()
      Retrieves a string representation of the client connection.

    • Method Detail

      • getConnectionID

        long getConnectionID()
        Retrieves the identifier that has been assigned to the associated client connection.
        Returns:
        The identifier that has been assigned to the associated client connection.

      • getClientConnectionPolicyName

        java.lang.String getClientConnectionPolicyName()
        Retrieves the name of the client connection policy to which the associated client connection is assigned. This may be an empty string if it uses the default client connection policy for internal connections.
        Returns:
        The name of the client connection policy to which the associated client connection is assigned.

      • getClientConnectionPolicyDN

        java.lang.String getClientConnectionPolicyDN()
        Retrieves the DN of the entry that defines the client connection policy to which the associated client connection is assigned. This may be an empty string if it uses the default client connection policy for internal connections.
        Returns:
        The DN of the entry that defines the client connection policy to which the associated client connection policy is assigned.

      • getMatchedConnectionCriteria

        java.util.List<java.lang.String> getMatchedConnectionCriteria()
        Returns a List containing the names of all the Connection Criteria that match this connection. These are the configuration names (e.g. the RDNs, not the full DNs) of the Connection Criteria.
        Returns:
        a list of connection criteria names.

      • matchesConnectionCriteria

        boolean matchesConnectionCriteria​(java.lang.String criteriaName)
        Determines whether this ClientContext matches the given Connection Criteria.
        Parameters:
        criteriaName - the name (not the DN) of the Connection Criteria to check against.
        Returns:
        true if this ClientContext matches the specified Connection Criteria, false otherwise.

      • isInternal

        boolean isInternal()
        Indicates whether this represents an internal client connection.
        Returns:
        true if this represents an internal client connection, or false if it is from an external client.

      • getInternalRootConnection

        InternalConnection getInternalRootConnection​(boolean usePolicyFromConnection)
        Retrieves an internal connection that is authenticated as a root user that is not subject to access control. It may optionally use the client connection policy from the associated client connection.
        Parameters:
        usePolicyFromConnection - If true, the internal connection will use the same client connection policy as the associated client connection. If false, the internal connection will use the server's default client connection policy for internal connections.
        Returns:
        An internal connection that is authenticated as a root user.

      • getInternalUserConnection

        InternalConnection getInternalUserConnection​(boolean usePolicyFromConnection)
                                      throws LDAPException
        Retrieves an internal connection that is authenticated as the same user as the associated client connection. It may optionally use the client connection policy from the associated client connection.
        Parameters:
        usePolicyFromConnection - If true, the internal connection will use the same client connection policy as the associated client connection. If false, the internal connection will use the server's default client connection policy for internal connections.
        Returns:
        An internal connection that is authenticated as the same user as the associated client connection.
        Throws:
        LDAPException - If a problem occurs while attempting to obtain or authenticate the connection.

      • getInternalConnection

        InternalConnection getInternalConnection​(java.lang.String dn,
                                         boolean usePolicyFromConnection)
                                  throws LDAPException
        Retrieves an internal connection that is authenticated as the specified user. Operations on the connection may be subject to access control based on the privileges associated with the specified user. It may optionally use the client connection policy from the associated client connection.
        Parameters:
        dn - The DN of the user as whom the connection should be authenticated. It may be null or empty if the connection should be unauthenticated.
        usePolicyFromConnection - If true, the internal connection will use the same client connection policy as the associated client connection. If false, the internal connection will use the server's default client connection policy for internal connections.
        Returns:
        An internal connection that is authenticated as the specified user.
        Throws:
        LDAPException - If a problem occurs while attempting to authenticate as the specified user.

      • isSecure

        boolean isSecure()
        Indicates whether the client is communicating with the server in a secure manner.
        Returns:
        true if the client is communicating with the server in a secure manner, or false if not.

      • getProtocol

        java.lang.String getProtocol()
        Retrieves the name of the protocol that the client is using to communicate with the server.
        Returns:
        The name of the protocol that the client is using to communicate with the server.

      • getConnectTime

        long getConnectTime()
        Retrieves the time that the connection was established. The value returned will be an offset in milliseconds since 12:00 a.m. on January 1, 1970.
        Returns:
        The time that the connection was established.

      • getClientInetAddress

        java.net.InetAddress getClientInetAddress()
        Retrieves an InetAddress representing the address of the client system, if available.
        Returns:
        An InetAddress representing the address of the client system, or null if that is not available or applicable for the associated client connection.

      • getServerInetAddress

        java.net.InetAddress getServerInetAddress()
        Retrieves an InetAddress representing the address on the server to which the client established the connection, if available.
        Returns:
        The address on the server to which the client established the connection, or null if that is not available or applicable.

      • isAuthenticated

        boolean isAuthenticated()
        Indicates whether the client has authenticated to the server.
        Returns:
        true if the client has authenticated to the server, or false if not.

      • getAuthInfo

        AuthInfo getAuthInfo()
        Retrieves information about the authentication state of the client connection.
        Returns:
        Information about the authentication state of the client connection.

      • isMemberOf

        boolean isMemberOf​(java.lang.String groupDN,
                   OperationContext operation)
            throws LDAPException
        Indicates whether the currently-authenticated user is a member of the specified group. This will consider both direct memberships (in which the user is explicitly named as a member of the target group) and indirect memberships (in which the user is a member of the group by virtue of matching dynamic group criteria or by membership in a nested group).
        Parameters:
        groupDN - The DN of the group for which to make the determination. It must not be null.
        operation - The operation currently being processed. It may be null if no operation is available.
        Returns:
        true if the authenticated user is a member of the specified group, or false if not.
        Throws:
        LDAPException - If a problem is encountered while attempting to make the determination.

      • getGroups

        java.util.Map<DN,​Group> getGroups​(OperationContext operation,
                                        boolean directMembershipOnly)
                                 throws LDAPException
        Retrieves the groups in which the currently-authenticated user is a member, indexed by group DN.
        Parameters:
        operation - The operation currently being processed. It may be null if no operation is available.
        directMembershipOnly - Indicates whether to only consider groups in which the user is directly named as a member. If this parameter is true, then only static groups that directly contain the authenticated user will be included. If this parameter is false, then the set of groups returned will also include dynamic groups in which the user's entry matches the membership criteria, as well as static groups in which the user is a nested member.
        Returns:
        The groups in which the currently-authenticated user is a member, or an empty map if the client connection is not authenticated or if the authenticated user is not a member of any groups.
        Throws:
        LDAPException - If a problem is encountered while attempting to determine the set of groups in which the authenticated user is a member.

      • hasPrivilege

        boolean hasPrivilege​(java.lang.String privilegeName,
                     OperationContext operation)
              throws LDAPException
        Indicates whether the currently-authenticated user has the specified privilege. The set of defined privileges may be found in the privilege-list.html and privilege-list.csv files in the server docs directory.
        Parameters:
        privilegeName - The name of the privilege for which to make the determination.
        operation - The operation currently being processed. It may be null if no operation is available.
        Returns:
        true if the currently-authenticated user has the specified privilege, or false if not (or if the client is not authenticated).
        Throws:
        LDAPException - If the specified privilege is not defined in the server, or if a problem is encountered while trying to make the determination.

      • getPrivilegeNames

        java.util.Set<java.lang.String> getPrivilegeNames()
        Retrieves the names of the privileges held by the currently-authenticated user. The set of defined privileges may be found in the privilege-list.html and privilege-list.csv files in the server docs directory.
        Returns:
        The names of the privileges held by the currently-authenticated user, or an empty set if the authenticated user does not have any privileges (or if the client is not authenticated).

      • sendUnsolicitedNotification

        void sendUnsolicitedNotification​(java.lang.String oid,
                                 ResultCode resultCode,
                                 java.lang.String message)
        Attempts to send an unsolicited notification to the client with the provided information.
        Parameters:
        oid - The OID for the unsolicited notification. It must not be null.
        resultCode - The result code to use for the unsolicited notification. It must not be null.
        message - A message to include in the unsolicited notification. It may be null if no message is needed.

      • disconnect

        void disconnect​(DisconnectReason reason,
                boolean notifyClient,
                java.lang.String message)
        Terminates the connection to the client and interrupts any operations that may be in progress on that connection.
        Parameters:
        reason - A general reason that the connection was closed.
        notifyClient - Indicates whether to attempt to send a notice of disconnection to the client.
        message - A message with information about the reason for the disconnect. It may be null if none is available. It is generally recommended that a message be provided even if the client should not be notified, since the message may be used in other ways (e.g., in log messages).

      • getServerContext

        ServerContext getServerContext()
        Retrieves information about the server with which the client connection is associated.
        Returns:
        Information about the server with which the client connection is associated.

      • getSASLAuthStateInfo

        java.lang.Object getSASLAuthStateInfo()
        Retrieves an opaque object with information about the state of an active multi-stage SASL bind. The core server will not make any attempt to interpret this object, but it is expected that any SASL mechanism handler which makes use of SASL state information will know how to interact with this object.
        Returns:
        An opaque object with information about the state of an active multi-stage SASL bind, or null if no state information is available (e.g., because no multi-stage SASL bind is in progress, or because no state information is needed for the active bind operation).

      • setSASLAuthStateInfo

        void setSASLAuthStateInfo​(java.lang.Object saslAuthStateInfo)
        Sets state information for an active multi-stage SASL bind. It is recommended that if any SASL state information is set in the connection, then that state should be cleared when it is no longer required (e.g., after the bind has completed or failed).
        Parameters:
        saslAuthStateInfo - An opaque object that may hold information about the state of an active multi-stage SASL bind. It may be null to clear any existing SASL authentication state. The core sever will not make any attempt to interpret this object, but it is expected that any SASL mechanism handler which makes use of SASL state information will know how to interact with this object.

      • getAttachment

        java.lang.Object getAttachment​(java.lang.String name)
        Retrieves a named object that has been associated with this client connection.
        Parameters:
        name - The name of the attachment to retrieve. It will be treated in a case-sensitive manner. Note that attachment names must be carefully crafted to avoid inadvertent conflicts between extensions or the core server itself. It is strongly recommended that attachment names be made unique (e.g., by prefixing them with the fully-qualified class name of the extension with which they are associated) so that attachments used by one extension do not inadvertently interfere with those which may be used in another extension or elsewhere in the server.
        Returns:
        The object that has been associated with this client connection using the given name, or null if there is no such attachment.

      • setAttachment

        java.lang.Object setAttachment​(java.lang.String name,
                               java.lang.Object value)
        Attaches an object to this client connection.
        Parameters:
        name - The name of the attachment to retrieve. It will be treated in a case-sensitive manner. Note that attachment names must be carefully crafted to avoid inadvertent conflicts between extensions or the core server itself. It is strongly recommended that attachment names be made unique (e.g., by prefixing them with the fully-qualified class name of the extension with which they are associated) so that attachments used by one extension do not inadvertently interfere with those which may be used in another extension or elsewhere in the server.
        value - The attachment to set. It may be null if an existing attachment with the given name should be removed.
        Returns:
        The attachment value held before the new value was assigned, or null if the attachment did not previously have a value.

      • toString

        java.lang.String toString()
        Retrieves a string representation of the client connection.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representation of the client connection.