org.opends.server.protocols.ldap
Class LDAPClientConnection

java.lang.Object
  org.opends.server.api.ClientConnection
      org.opends.server.protocols.ldap.LDAPClientConnection

All Implemented Interfaces:

TLSCapableConnection

public class LDAPClientConnection
extends ClientConnection
implements TLSCapableConnection

This class defines an LDAP client connection, which is a type of client connection that will be accepted by an instance of the LDAP connection handler and have its requests decoded by an LDAP request handler.

Constructor Summary

LDAPClientConnection(LDAPConnectionHandler connectionHandler, java.nio.channels.SocketChannel clientChannel)
Creates a new LDAP client connection with the provided information.

Method Summary

void	addOperationInProgress(AbstractOperation operation) Adds the provided operation to the set of operations in progress for this client connection.
void	cancelAllOperations(CancelRequest cancelRequest) Attempts to cancel all operations in progress on this connection.
void	cancelAllOperationsExcept(CancelRequest cancelRequest, int messageID) Attempts to cancel all operations in progress on this connection except the operation with the specified message ID.
CancelResult	cancelOperation(int messageID, CancelRequest cancelRequest) Attempts to cancel the specified operation.
void	disableTLSConnectionSecurityProvider() Disables the TLS connection security provider on this client connection.
void	disconnect(DisconnectReason disconnectReason, boolean sendNotification, Message message) Closes the connection to the client, optionally sending it a message indicating the reason for the closure.
void	enableTLSConnectionSecurityProvider() Installs the TLS connection security provider on this client connection.
java.lang.String	getCertificateAlias() Retrieves the alias of the server certificate that should be used for operations requiring a server certificate.
java.lang.String	getClientAddress() Retrieves a string representation of the address of the client.
java.lang.String	getClientHostPort() Retrieves the address and port of the client system, separated by a colon.
int	getClientPort() Retrieves the port number for this connection on the client system.
ConnectionHandler	getConnectionHandler() Retrieves the connection handler that accepted this client connection.
long	getConnectionID() Retrieves the connection ID assigned to this connection.
ConnectionSecurityProvider	getConnectionSecurityProvider() Retrieves the connection security provider for this client connection.
long	getIdleTime() Retrieves the length of time in milliseconds that this client connection has been idle.
DN	getKeyManagerProviderDN() Retrieves the DN of the key manager provider that should be used for operations requiring access to a key manager.
java.net.InetAddress	getLocalAddress() Retrieves the java.net.InetAddress for the Directory Server system to which the client has established the connection.
long	getMaxBlockedWriteTimeLimit() Retrieves the maximum length of time in milliseconds that attempts to write data to the client should be allowed to block.
java.lang.String	getMonitorSummary() Retrieves a one-line summary of this client connection in a form that is suitable for including in the monitor entry for the associated connection handler.
AbstractOperation	getOperationInProgress(int messageID) Retrieves the operation in progress with the specified message ID.
java.util.Collection<AbstractOperation>	getOperationsInProgress() Retrieves the set of operations in progress for this client connection.
java.lang.String	getProtocol() Retrieves the protocol that the client is using to communicate with the Directory Server.
java.net.InetAddress	getRemoteAddress() Retrieves the java.net.InetAddress associated with the remote client system.
LDAPRequestHandler	getRequestHandler() Retrieves the request handler that will read requests for this client connection.
java.lang.String	getSecurityMechanism() Retrieves the human-readable name of the security mechanism that is used to protect communication with this client.
java.lang.String	getServerAddress() Retrieves a string representation of the address on the server to which the client connected.
java.lang.String	getServerHostPort() Retrieves the address and port of the server system, separated by a colon.
int	getServerPort() Retrieves the port number for this connection on the server system.
java.nio.channels.SocketChannel	getSocketChannel() Retrieves the socket channel that can be used to communicate with the client.
DN	getTrustManagerProviderDN() Retrieves the DN of the trust manager provider that should be used for operations requiring access to a trust manager.
java.nio.channels.Selector	getWriteSelector() Retrieves a Selector that may be used to ensure that write operations complete in a timely manner, or terminate the connection in the event that they fail to do so.
boolean	isSecure() Indicates whether this client connection is currently using a secure mechanism to communicate with the server.
long	nextOperationID() Retrieves the next operation ID that should be used for this connection.
boolean	processDataRead(java.nio.ByteBuffer buffer) Process the information contained in the provided byte buffer as an ASN.1 element.
boolean	removeOperationInProgress(int messageID) Removes the provided operation from the set of operations in progress for this client connection.
void	sendClearResponse(Operation operation) Sends a response to the client in the clear rather than through the encrypted channel.
protected boolean	sendIntermediateResponseMessage(IntermediateResponse intermediateResponse) Sends the provided intermediate response message to the client.
void	sendLDAPMessage(ConnectionSecurityProvider secProvider, LDAPMessage message) Sends the provided LDAP message to the client.
void	sendResponse(Operation operation) Sends a response to the client based on the information in the provided operation.
void	sendSearchEntry(SearchOperation searchOperation, SearchResultEntry searchEntry) Sends the provided search result entry to the client.
boolean	sendSearchReference(SearchOperation searchOperation, SearchResultReference searchReference) Sends the provided search result reference to the client.
void	setConnectionSecurityProvider(ConnectionSecurityProvider securityProvider) Specifies the connection security provider for this client connection.
void	setRequestHandler(LDAPRequestHandler requestHandler) Specifies the request handler that will read requests for this client connection.
boolean	tlsProtectionAvailable(MessageBuilder unavailableReason) Indicates whether TLS protection is actually available for the underlying client connection.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this client connection to the provided buffer.

Methods inherited from class org.opends.server.api.ClientConnection

bindInProgress, deregisterPersistentSearch, finalize, finalizeClientConnection, finalizeConnectionInternal, getAuthenticationInfo, getConnectTime, getConnectTimeString, getGroups, getIdleTimeLimit, getLookthroughLimit, getNetworkGroup, getPersistentSearches, getSASLAuthStateInfo, getSizeLimit, getTimeLimit, hasAllPrivileges, hasPrivilege, isMemberOf, mustChangePassword, registerPersistentSearch, sendIntermediateResponse, setAuthenticationInfo, setBindInProgress, setIdleTimeLimit, setLookthroughLimit, setMustChangePassword, setNetworkGroup, setSASLAuthStateInfo, setSizeLimit, setTimeLimit, setUnauthenticated, toString, updateAuthenticationInfo

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LDAPClientConnection

public LDAPClientConnection(LDAPConnectionHandler connectionHandler,
                            java.nio.channels.SocketChannel clientChannel)

Creates a new LDAP client connection with the provided information.

Parameters:

connectionHandler - The connection handler that accepted this connection.

clientChannel - The socket channel that may be used to communicate with the client.

Method Detail

getConnectionID

public long getConnectionID()

Retrieves the connection ID assigned to this connection.

Specified by:

getConnectionID in class ClientConnection

Returns:

The connection ID assigned to this connection.

getConnectionHandler

public ConnectionHandler getConnectionHandler()

Retrieves the connection handler that accepted this client connection.

Specified by:

getConnectionHandler in class ClientConnection

Returns:

The connection handler that accepted this client connection.

getRequestHandler

public LDAPRequestHandler getRequestHandler()

Retrieves the request handler that will read requests for this client connection.

Returns:

The request handler that will read requests for this client connection, or null if none has been assigned yet.

setRequestHandler

public void setRequestHandler(LDAPRequestHandler requestHandler)

Specifies the request handler that will read requests for this client connection.

Parameters:

requestHandler - The request handler that will read requests for this client connection.

getSocketChannel

public java.nio.channels.SocketChannel getSocketChannel()

Retrieves the socket channel that can be used to communicate with the client.

Returns:

The socket channel that can be used to communicate with the client.

getProtocol

public java.lang.String getProtocol()

Retrieves the protocol that the client is using to communicate with the Directory Server.

Specified by:

getProtocol in class ClientConnection

Returns:

The protocol that the client is using to communicate with the Directory Server.

getClientAddress

public java.lang.String getClientAddress()

Retrieves a string representation of the address of the client.

Specified by:

getClientAddress in class ClientConnection

Returns:

A string representation of the address of the client.

getClientPort

public int getClientPort()

Retrieves the port number for this connection on the client system.

Returns:

The port number for this connection on the client system.

getClientHostPort

public java.lang.String getClientHostPort()

Retrieves the address and port of the client system, separated by a colon.

Returns:

The address and port of the client system, separated by a colon.

getServerAddress

public java.lang.String getServerAddress()

Retrieves a string representation of the address on the server to which the client connected.

Specified by:

getServerAddress in class ClientConnection

Returns:

A string representation of the address on the server to which the client connected.

getServerPort

public int getServerPort()

Retrieves the port number for this connection on the server system.

Returns:

The port number for this connection on the server system.

getServerHostPort

public java.lang.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 java.net.InetAddress getRemoteAddress()

Retrieves the java.net.InetAddress associated with the remote client system.

Specified by:

getRemoteAddress in class ClientConnection

Returns:

The java.net.InetAddress associated with the remote client system. It may be null if the client is not connected over an IP-based connection.

getLocalAddress

public java.net.InetAddress getLocalAddress()

Retrieves the java.net.InetAddress for the Directory Server system to which the client has established the connection.

Specified by:

getLocalAddress in class ClientConnection

Returns:

The java.net.InetAddress for the Directory Server system to which the client has established the connection. It may be null if the client is not connected over an IP-based connection.

isSecure

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

Specified by:

isSecure in class ClientConnection

Returns:

true if the client connection is currently using a secure mechanism to communicate with the server, or false if not.

getConnectionSecurityProvider

public ConnectionSecurityProvider getConnectionSecurityProvider()

Retrieves the connection security provider for this client connection.

Specified by:

getConnectionSecurityProvider in class ClientConnection

Returns:

The connection security provider for this client connection.

setConnectionSecurityProvider

public void setConnectionSecurityProvider(ConnectionSecurityProvider securityProvider)

Specifies the connection security provider for this client connection.

Specified by:

setConnectionSecurityProvider in class ClientConnection

Parameters:

securityProvider - The connection security provider to use for communication on this client connection.

getSecurityMechanism

public java.lang.String getSecurityMechanism()

Retrieves the human-readable name of the security mechanism that is used to protect communication with this client.

Specified by:

getSecurityMechanism in class ClientConnection

Returns:

The human-readable name of the security mechanism that is used to protect communication with this client, or null if no security is in place.

nextOperationID

public long nextOperationID()

Retrieves the next operation ID that should be used for this connection.

Returns:

The next operation ID that should be used for this connection.

sendResponse

public void sendResponse(Operation operation)

Sends a response to the client based on the information in the provided operation.

Specified by:

sendResponse in class ClientConnection

Parameters:

operation - The operation for which to send the response.

sendSearchEntry

public void sendSearchEntry(SearchOperation searchOperation,
                            SearchResultEntry searchEntry)

Sends the provided search result entry to the client.

Specified by:

sendSearchEntry in class ClientConnection

Parameters:

searchOperation - The search operation with which the entry is associated.

searchEntry - The search result entry to be sent to the client.

sendSearchReference

public boolean sendSearchReference(SearchOperation searchOperation,
                                   SearchResultReference searchReference)

Sends the provided search result reference to the client.

Specified by:

sendSearchReference in class ClientConnection

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 boolean sendIntermediateResponseMessage(IntermediateResponse intermediateResponse)

Sends the provided intermediate response message to the client.

Specified by:

sendIntermediateResponseMessage in class ClientConnection

Parameters:

intermediateResponse - The intermediate response message to be sent.

Returns:

true if processing on the associated operation should continue, or false if not.

sendLDAPMessage

public void sendLDAPMessage(ConnectionSecurityProvider secProvider,
                            LDAPMessage message)

Sends the provided LDAP message to the client.

Parameters:

secProvider - The connection security provider to use to handle any necessary security translation.

message - The LDAP message to send to the client.

disconnect

public void disconnect(DisconnectReason disconnectReason,
                       boolean sendNotification,
                       Message 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.

Specified by:

disconnect in class ClientConnection

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 include in the disconnect notification response. It may be null if no message is to be sent.

getOperationsInProgress

public java.util.Collection<AbstractOperation> getOperationsInProgress()

Retrieves the set of operations in progress for this client connection. This list must not be altered by any caller.

Specified by:

getOperationsInProgress in class ClientConnection

Returns:

The set of operations in progress for this client connection.

getOperationInProgress

public AbstractOperation getOperationInProgress(int messageID)

Retrieves the operation in progress with the specified message ID.

Specified by:

getOperationInProgress in class ClientConnection

Parameters:

messageID - The message ID for the operation to retrieve.

Returns:

The operation in progress with the specified message ID, or null if no such operation could be found.

addOperationInProgress

public void addOperationInProgress(AbstractOperation operation)
                            throws DirectoryException

Adds the provided operation to the set of operations in progress for this client connection.

Parameters:

operation - The operation to add to the set of operations in progress for this client connection.

Throws:

DirectoryException - If the operation is not added for some reason (e.g., the client already has reached the maximum allowed concurrent requests).

removeOperationInProgress

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

Specified by:

removeOperationInProgress in class ClientConnection

Parameters:

messageID - The message ID of the operation to remove from the set of operations in progress.

Returns:

true if the operation was found and removed from the set of operations in progress, or false if not.

cancelOperation

public CancelResult cancelOperation(int messageID,
                                    CancelRequest cancelRequest)

Attempts to cancel the specified operation.

Specified by:

cancelOperation in class ClientConnection

Parameters:

messageID - The message ID of the operation to cancel.

cancelRequest - An object providing additional information about how the cancel should be processed.

Returns:

A cancel result that either indicates that the cancel was successful or provides a reason that it was not.

cancelAllOperations

public void cancelAllOperations(CancelRequest cancelRequest)

Attempts to cancel all operations in progress on this connection.

Specified by:

cancelAllOperations in class ClientConnection

Parameters:

cancelRequest - An object providing additional information about how the cancel should be processed.

cancelAllOperationsExcept

public void cancelAllOperationsExcept(CancelRequest cancelRequest,
                                      int messageID)

Attempts to cancel all operations in progress on this connection except the operation with the specified message ID.

Specified by:

cancelAllOperationsExcept in class ClientConnection

Parameters:

cancelRequest - An object providing additional information about how the cancel should be processed.

messageID - The message ID of the operation that should not be canceled.

getWriteSelector

public java.nio.channels.Selector getWriteSelector()

Retrieves a Selector that may be used to ensure that write operations complete in a timely manner, or terminate the connection in the event that they fail to do so. This is an optional method for client connections, and the default implementation returns null to indicate that the maximum blocked write time limit is not supported for this connection. Subclasses that do wish to support this functionality should return a valid Selector object.

Overrides:

getWriteSelector in class ClientConnection

Returns:

The Selector that may be used to ensure that write operations complete in a timely manner, or null if this client connection does not support maximum blocked write time limit functionality.

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. A value of zero indicates there should be no limit.

Overrides:

getMaxBlockedWriteTimeLimit in class ClientConnection

Returns:

The maximum length of time in milliseconds that attempts to write data to the client should be allowed to block, or zero if there should be no limit.

processDataRead

public boolean processDataRead(java.nio.ByteBuffer buffer)

Process the information contained in the provided byte buffer as an ASN.1 element. It may take several calls to this method in order to get all the information necessary to decode a single ASN.1 element, but it may also be possible that there are multiple elements (or at least fragments of multiple elements) in a single buffer. This will fully process whatever the client provided and set up the appropriate state information to make it possible to pick up in the right place the next time around.

Specified by:

processDataRead in class ClientConnection

Parameters:

buffer - The buffer containing the data to be processed. It must be ready for reading (i.e., it should have been flipped by the caller), and the data provided must be unencrypted (e.g., if the client is communicating over SSL, then the decryption should happen before calling this method).

Returns:

true if all the data in the provided buffer was processed and the client connection can remain established, or false if a decoding error occurred and requests from this client should no longer be processed. Note that if this method does return false, then it must have already disconnected the client, and upon returning the request handler should remove it from the associated selector.

getMonitorSummary

public java.lang.String getMonitorSummary()

Retrieves a one-line summary of this client connection in a form that is suitable for including in the monitor entry for the associated connection handler. It should be in a format that is both humand readable and machine parseable (e.g., a space-delimited name-value list, with quotes around the values).

Specified by:

getMonitorSummary in class ClientConnection

Returns:

A one-line summary of this client connection in a form that is suitable for including in the monitor entry for the associated connection handler.

toString

public void toString(java.lang.StringBuilder buffer)

Appends a string representation of this client connection to the provided buffer.

Specified by:

toString in class ClientConnection

Parameters:

buffer - The buffer to which the information should be appended.

tlsProtectionAvailable

public boolean tlsProtectionAvailable(MessageBuilder unavailableReason)

Indicates whether TLS protection is actually available for the underlying client connection. If there is any reason that TLS protection cannot be enabled on this client connection, then it should be appended to the provided buffer.

Specified by:

tlsProtectionAvailable in interface TLSCapableConnection

Parameters:

unavailableReason - The buffer used to hold the reason that TLS is not available on the underlying client connection.

Returns:

true if TLS is available on the underlying client connection, or false if it is not.

enableTLSConnectionSecurityProvider

public void enableTLSConnectionSecurityProvider()
                                         throws DirectoryException

Installs the TLS connection security provider on this client connection. If an error occurs in the process, then the underlying client connection must be terminated and an exception must be thrown to indicate the underlying cause.

Specified by:

enableTLSConnectionSecurityProvider in interface TLSCapableConnection

Throws:

DirectoryException - If the TLS connection security provider could not be enabled and the underlying connection has been closed.

disableTLSConnectionSecurityProvider

public void disableTLSConnectionSecurityProvider()
                                          throws DirectoryException

Disables the TLS connection security provider on this client connection. This must also eliminate any authentication that had been performed on the client connection so that it is in an anonymous state. If a problem occurs while attempting to revert the connection to a non-TLS-protected state, then an exception must be thrown and the client connection must be terminated.

Specified by:

disableTLSConnectionSecurityProvider in interface TLSCapableConnection

Throws:

DirectoryException - If TLS protection cannot be reverted and the underlying client connection has been closed.

sendClearResponse

public void sendClearResponse(Operation operation)
                       throws DirectoryException

Sends a response to the client in the clear rather than through the encrypted channel. This should only be used when processing the StartTLS extended operation to send the response in the clear after the TLS negotiation has already been initiated.

Specified by:

sendClearResponse in interface TLSCapableConnection

Parameters:

operation - The operation for which to send the response in the clear.

Throws:

DirectoryException - If a problem occurs while sending the response in the clear.

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 avaialble, but subclasses should override this method to return a valid DN if they perform operations which may need access to a key manager.

Overrides:

getKeyManagerProviderDN in class ClientConnection

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.

getTrustManagerProviderDN

public DN getTrustManagerProviderDN()

Retrieves the DN of the trust manager provider that should be used for operations requiring access to a trust manager. The default implementation returns null to indicate that no trust manager provider is avaialble, but subclasses should override this method to return a valid DN if they perform operations which may need access to a trust manager.

Overrides:

getTrustManagerProviderDN in class ClientConnection

Returns:

The DN of the trust manager provider that should be used for operations requiring access to a trust manager, or null if there is no trust manager provider configured for this client connection.

getCertificateAlias

public java.lang.String getCertificateAlias()

Retrieves the alias of the server certificate that should be used for operations requiring a server certificate. The default implementation returns null to indicate that any alias is acceptable.

Overrides:

getCertificateAlias in class ClientConnection

Returns:

The alias of the server certificate that should be used for operations requring a server certificate, or null if any alias is acceptable.

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.

Overrides:

getIdleTime in class ClientConnection

Returns:

The length of time in milliseconds that this client connection has been idle.