com.unboundid.directory.sdk.common.types

Interface ClientContext

@NotExtensible
 @ThreadSafety(level=INTERFACE_NOT_THREADSAFE)
public interface ClientContext

This interface defines a set of methods that may be used to obtain information about a client connection that has been established to the server.

Method Summary

Modifier and Type	Method and 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.