com.unboundid.ldap.listener

Class LDAPListenerClientConnection

java.lang.Object

java.lang.Thread

com.unboundid.ldap.listener.LDAPListenerClientConnection

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, java.lang.Runnable

@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class LDAPListenerClientConnection
extends java.lang.Thread
implements java.io.Closeable

This class provides an object which will be used to represent a connection to a client accepted by an LDAPListener, although connections may also be created independently if they were accepted in some other way. Each connection has its own thread that will be used to read requests from the client, and connections created outside of an LDAPListener instance, then the thread must be explicitly started.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
LDAPListenerClientConnection(LDAPListener listener, java.net.Socket socket, LDAPListenerRequestHandler requestHandler, LDAPListenerExceptionHandler exceptionHandler) Creates a new LDAP listener client connection that will communicate with the client using the provided socket.

Method Summary

Modifier and Type	Method and Description
void	addIntermediateResponseTransformer(IntermediateResponseTransformer t) Adds the provided intermediate response transformer to this client connection.
void	addSearchEntryTransformer(SearchEntryTransformer t) Adds the provided search entry transformer to this client connection.
void	addSearchReferenceTransformer(SearchReferenceTransformer t) Adds the provided search reference transformer to this client connection.
void	close() Closes the connection to the client.
java.io.OutputStream	convertToTLS(javax.net.ssl.SSLSocketFactory sslSocketFactory) Attempts to convert this unencrypted connection to one that uses TLS encryption, as would be used during the course of invoking the StartTLS extended operation.
java.io.OutputStream	convertToTLS(javax.net.ssl.SSLSocketFactory sslSocketFactory, boolean requestClientCertificate, boolean requireClientCertificate) Attempts to convert this unencrypted connection to one that uses TLS encryption, as would be used during the course of invoking the StartTLS extended operation.
long	getConnectionID() Retrieves the connection ID that has been assigned to this connection by the associated listener.
java.net.Socket	getSocket() Retrieves the socket used to communicate with the client.
void	removeIntermediateResponseTransformer(IntermediateResponseTransformer t) Removes the provided intermediate response transformer from this client connection.
void	removeSearchEntryTransformer(SearchEntryTransformer t) Removes the provided search entry transformer from this client connection.
void	removeSearchReferenceTransformer(SearchReferenceTransformer t) Removes the provided search reference transformer from this client connection.
void	run() Operates in a loop, waiting for a request to arrive from the client and handing it off to the request handler for processing.
void	sendIntermediateResponse(int messageID, IntermediateResponseProtocolOp protocolOp, Control... controls) Sends an intermediate response message to the client with the provided information.
void	sendSearchResultEntry(int messageID, Entry entry, Control... controls) Sends a search result entry message to the client with the provided information.
void	sendSearchResultEntry(int messageID, SearchResultEntryProtocolOp protocolOp, Control... controls) Sends a search result entry message to the client with the provided information.
void	sendSearchResultReference(int messageID, SearchResultReferenceProtocolOp protocolOp, Control... controls) Sends a search result reference message to the client with the provided information.
void	sendUnsolicitedNotification(ExtendedResponseProtocolOp extendedResponse, Control... controls) Sends an unsolicited notification message to the client with the provided information.
void	sendUnsolicitedNotification(ExtendedResult result) Sends an unsolicited notification message to the client with the provided extended result.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LDAPListenerClientConnection

public LDAPListenerClientConnection(@Nullable
                                    LDAPListener listener,
                                    @NotNull
                                    java.net.Socket socket,
                                    @NotNull
                                    LDAPListenerRequestHandler requestHandler,
                                    @Nullable
                                    LDAPListenerExceptionHandler exceptionHandler)
                             throws LDAPException

Creates a new LDAP listener client connection that will communicate with the client using the provided socket. The Thread.start() method must be called to start listening for requests from the client.

Parameters:

listener - The listener that accepted this client connection. It may be null if this connection was not accepted by a listener.

socket - The socket that may be used to communicate with the client. It must not be null.

requestHandler - The request handler that will be used to process requests read from the client. The LDAPListenerRequestHandler.newInstance(com.unboundid.ldap.listener.LDAPListenerClientConnection) method will be called on the provided object to obtain a new instance to use for this connection. The provided request handler must not be null.

exceptionHandler - The disconnect handler to be notified when this connection is closed. It may be null if no disconnect handler should be used.

Throws:

LDAPException - If a problem occurs while preparing this client connection. for use. If this is thrown, then the provided socket will be closed.

Method Detail

close

public void close()
           throws java.io.IOException

Closes the connection to the client.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException - If a problem occurs while closing the socket.

run

@InternalUseOnly
public void run()

Operates in a loop, waiting for a request to arrive from the client and handing it off to the request handler for processing. This method is for internal use only and must not be invoked by external callers.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

sendSearchResultEntry

public void sendSearchResultEntry(int messageID,
                                  @NotNull
                                  SearchResultEntryProtocolOp protocolOp,
                                  @Nullable
                                  Control... controls)
                           throws LDAPException

Sends a search result entry message to the client with the provided information.

Parameters:

messageID - The message ID for the LDAP message to send to the client. It must match the message ID of the associated search request.

protocolOp - The search result entry protocol op to include in the LDAP message to send to the client. It must not be null.

controls - The set of controls to include in the response message. It may be empty or null if no controls should be included.

Throws:

LDAPException - If a problem occurs while attempting to send the provided response message. If an exception is thrown, then the client connection will have been terminated.

sendSearchResultEntry

public void sendSearchResultEntry(int messageID,
                                  @NotNull
                                  Entry entry,
                                  @Nullable
                                  Control... controls)
                           throws LDAPException

Sends a search result entry message to the client with the provided information.

Parameters:

messageID - The message ID for the LDAP message to send to the client. It must match the message ID of the associated search request.

entry - The entry to return to the client. It must not be null.

controls - The set of controls to include in the response message. It may be empty or null if no controls should be included.

Throws:

LDAPException - If a problem occurs while attempting to send the provided response message. If an exception is thrown, then the client connection will have been terminated.

sendSearchResultReference

public void sendSearchResultReference(int messageID,
                                      @NotNull
                                      SearchResultReferenceProtocolOp protocolOp,
                                      @Nullable
                                      Control... controls)
                               throws LDAPException

Sends a search result reference message to the client with the provided information.

Parameters:

messageID - The message ID for the LDAP message to send to the client. It must match the message ID of the associated search request.

protocolOp - The search result reference protocol op to include in the LDAP message to send to the client.

controls - The set of controls to include in the response message. It may be empty or null if no controls should be included.

Throws:

LDAPException - If a problem occurs while attempting to send the provided response message. If an exception is thrown, then the client connection will have been terminated.

sendIntermediateResponse

public void sendIntermediateResponse(int messageID,
                                     @NotNull
                                     IntermediateResponseProtocolOp protocolOp,
                                     @Nullable
                                     Control... controls)
                              throws LDAPException

Sends an intermediate response message to the client with the provided information.

Parameters:

messageID - The message ID for the LDAP message to send to the client. It must match the message ID of the associated search request.

protocolOp - The intermediate response protocol op to include in the LDAP message to send to the client.

controls - The set of controls to include in the response message. It may be empty or null if no controls should be included.

Throws:

LDAPException - If a problem occurs while attempting to send the provided response message. If an exception is thrown, then the client connection will have been terminated.

sendUnsolicitedNotification

public void sendUnsolicitedNotification(@NotNull
                                        ExtendedResult result)
                                 throws LDAPException

Sends an unsolicited notification message to the client with the provided extended result.

Parameters:

result - The extended result to use for the unsolicited notification.

Throws:

LDAPException - If a problem occurs while attempting to send the unsolicited notification. If an exception is thrown, then the client connection will have been terminated.

sendUnsolicitedNotification

public void sendUnsolicitedNotification(@NotNull
                                        ExtendedResponseProtocolOp extendedResponse,
                                        @Nullable
                                        Control... controls)
                                 throws LDAPException

Sends an unsolicited notification message to the client with the provided information.

Parameters:

extendedResponse - The extended response to use for the unsolicited notification.

controls - The set of controls to include with the unsolicited notification. It may be empty or null if no controls should be included.

Throws:

LDAPException - If a problem occurs while attempting to send the unsolicited notification. If an exception is thrown, then the client connection will have been terminated.

getSocket

@NotNull
public java.net.Socket getSocket()

Retrieves the socket used to communicate with the client.

Returns:

The socket used to communicate with the client.

convertToTLS

@NotNull
public java.io.OutputStream convertToTLS(@NotNull
                                                  javax.net.ssl.SSLSocketFactory sslSocketFactory)
                                           throws LDAPException

Attempts to convert this unencrypted connection to one that uses TLS encryption, as would be used during the course of invoking the StartTLS extended operation. If this is called, then the response that would have been returned from the associated request will be suppressed, so the returned output stream must be used to send the appropriate response to the client.

Parameters:

sslSocketFactory - The SSL socket factory that will be used to convert the existing Socket to an SSLSocket.

Returns:

An output stream that can be used to send a clear-text message to the client (e.g., the StartTLS response message).

Throws:

LDAPException - If a problem is encountered while trying to convert the existing socket to an SSL socket. If this is thrown, then the connection will have been closed.

convertToTLS

@NotNull
public java.io.OutputStream convertToTLS(@NotNull
                                                  javax.net.ssl.SSLSocketFactory sslSocketFactory,
                                                  boolean requestClientCertificate,
                                                  boolean requireClientCertificate)
                                           throws LDAPException

Attempts to convert this unencrypted connection to one that uses TLS encryption, as would be used during the course of invoking the StartTLS extended operation. If this is called, then the response that would have been returned from the associated request will be suppressed, so the returned output stream must be used to send the appropriate response to the client.

Parameters:

sslSocketFactory - The SSL socket factory that will be used to convert the existing Socket to an SSLSocket.

requestClientCertificate - Indicates whether the listener should request that the client present its own certificate chain during TLS negotiation. This will be ignored for non-TLS-based connections.

requireClientCertificate - Indicates whether the listener should require that the client present its own certificate chain during TLS negotiation, and should fail negotiation if the client does not present one. This will be ignored for non-TLS-based connections or if requestClientCertificate is false.

Returns:

An output stream that can be used to send a clear-text message to the client (e.g., the StartTLS response message).

Throws:

LDAPException - If a problem is encountered while trying to convert the existing socket to an SSL socket. If this is thrown, then the connection will have been closed.

getConnectionID

public long getConnectionID()

Retrieves the connection ID that has been assigned to this connection by the associated listener.

Returns:

The connection ID that has been assigned to this connection by the associated listener, or -1 if it is not associated with a listener.

addSearchEntryTransformer

public void addSearchEntryTransformer(@NotNull
                                      SearchEntryTransformer t)

Adds the provided search entry transformer to this client connection.

Parameters:

t - A search entry transformer to be used to intercept and/or alter search result entries before they are returned to the client.

removeSearchEntryTransformer

public void removeSearchEntryTransformer(@NotNull
                                         SearchEntryTransformer t)

Removes the provided search entry transformer from this client connection.

Parameters:

t - The search entry transformer to be removed.

addSearchReferenceTransformer

public void addSearchReferenceTransformer(@NotNull
                                          SearchReferenceTransformer t)

Adds the provided search reference transformer to this client connection.

Parameters:

t - A search reference transformer to be used to intercept and/or alter search result references before they are returned to the client.

removeSearchReferenceTransformer

public void removeSearchReferenceTransformer(@NotNull
                                             SearchReferenceTransformer t)

Removes the provided search reference transformer from this client connection.

Parameters:

t - The search reference transformer to be removed.

addIntermediateResponseTransformer

public void addIntermediateResponseTransformer(@NotNull
                                               IntermediateResponseTransformer t)

Adds the provided intermediate response transformer to this client connection.

Parameters:

t - An intermediate response transformer to be used to intercept and/or alter intermediate responses before they are returned to the client.

removeIntermediateResponseTransformer

public void removeIntermediateResponseTransformer(@NotNull
                                                  IntermediateResponseTransformer t)

Removes the provided intermediate response transformer from this client connection.

Parameters:

t - The intermediate response transformer to be removed.