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

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.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.
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.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	isAuthenticated() Indicates whether the client has authenticated to the server.
boolean	isInternal() Indicates whether this represents an internal client connection.
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, com.unboundid.ldap.sdk.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.

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 com.unboundid.ldap.sdk.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:

com.unboundid.ldap.sdk.LDAPException - If a problem occurs while attempting to obtain or authenticate the connection.

getInternalConnection

InternalConnection getInternalConnection(java.lang.String dn,
                                         boolean usePolicyFromConnection)
                                         throws com.unboundid.ldap.sdk.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:

com.unboundid.ldap.sdk.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.

sendUnsolicitedNotification

void sendUnsolicitedNotification(java.lang.String oid,
                                 com.unboundid.ldap.sdk.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.