Connection

Class Overview

A thread that creates a connection to an LDAP server. After the connection, the thread reads from the connection. A caller can invoke methods on the instance to read LDAP responses and to send LDAP requests.

There is a one-to-one correspondence between an LdapClient and a Connection. Access to Connection and its methods is only via LdapClient with two exceptions: SASL authentication and StartTLS. SASL needs to access Connection's socket IO streams (in order to do encryption of the security layer). StartTLS needs to do replace IO streams and close the IO streams on nonfatal close. The code for SASL authentication can be treated as being the same as from LdapClient because the SASL code is only ever called from LdapClient, from inside LdapClient's synchronized authenticate() method. StartTLS is called directly by the application but should only occur when the underlying connection is quiet.

In terms of synchronization, worry about data structures used by the Connection thread because that usage might contend with calls by the main threads (i.e., those that call LdapClient). Main threads need to worry about contention with each other. Fields that Connection thread uses: inStream - synced access and update; initialized in constructor; referenced outside class unsync'ed (by LdapSasl) only when connection is quiet traceFile, traceTagIn, traceTagOut - no sync; debugging only parent - no sync; initialized in constructor; no updates pendingRequests - sync pauseLock - per-instance lock; paused - sync via pauseLock (pauseReader()) Members used by main threads (LdapClient): host, port - unsync; read-only access for StartTLS and debug messages setBound(), setV3() - no sync; called only by LdapClient.authenticate(), which is a sync method called only when connection is "quiet" getMsgId() - sync writeRequest(), removeRequest(),findRequest(), abandonOutstandingReqs() - access to shared pendingRequests is sync writeRequest(), abandonRequest(), ldapUnbind() - access to outStream sync cleanup() - sync readReply() - access to sock sync unpauseReader() - (indirectly via writeRequest) sync on pauseLock Members used by SASL auth (main thread): inStream, outStream - no sync; used to construct new stream; accessed only when conn is "quiet" and not shared replaceStreams() - sync method Members used by StartTLS: inStream, outStream - no sync; used to record the existing streams; accessed only when conn is "quiet" and not shared replaceStreams() - sync method

Handles anonymous, simple, and SASL bind for v3; anonymous and simple for v2. %%% made public for access by LdapSasl %%%

Summary

[Expand] Inherited Methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait() Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object. final void wait(long timeout, int nanos) Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. final void wait(long timeout) Causes the current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed.
From interface java.lang.Runnable abstract void run() When an object implementing interface Runnable is used to create a thread, starting the thread causes the object's run method to be called in that separately executing thread.