All LDAP Classes
Internal LDAP Classes

com.novell.ldap
Class Connection

java.lang.Object
  extended by com.novell.ldap.Connection

final class Connection
extends java.lang.Object

The class that creates a connection to the LDAP server. After the connection is made, a thread is created that reads data from the connection.

The application's thread sends a request to the MessageAgent class, which creates a Message class. The Message class calls the writeMessage method of this class to send the request to the server. The application thread will then query the MessageAgent class for a response.

The reader thread multiplexes response messages received from the server to the appropriate Message class. Each Message class has its own message queue.

Unsolicited messages are process separately, and if the application has registered a handler, a separate thread is created for that application's handler to process the message.

Note: the reader thread must not be a "selfish" thread, since some operating systems do not time slice.


Nested Class Summary
 class Connection.ReaderThread
           
private  class Connection.UnsolicitedListenerThread
          Inner class defined so that we can spawn off each unsolicited listener as a seperate thread.
 
Field Summary
private  ReferralInfo activeReferral
           
private  BindProperties bindProperties
           
private  int bindSemaphoreId
           
private  boolean clientActive
           
private  int cloneCount
           
private static int connNum
           
private static int CONTINUE_READING
           
private  java.lang.Thread deadReader
           
private  java.io.IOException deadReaderException
           
private  LBERDecoder decoder
           
private  LBEREncoder encoder
           
private  int ephemeralId
           
private  java.lang.String host
           
private  java.io.InputStream in
           
private  MessageVector messages
           
private  LDAPSocketFactory mySocketFactory
           
private  int myTimeOut
           
private  java.lang.String name
           
private static java.lang.Object nameLock
           
private  java.net.Socket nonTLSBackup
           
private  java.io.OutputStream out
           
private  int port
           
(package private) static java.lang.Integer protocol
           
private  java.lang.Thread reader
           
(package private) static java.lang.String sdk
           
(package private) static java.lang.String security
           
private  java.net.Socket socket
           
private static LDAPSocketFactory socketFactory
           
private static int STOP_READING
           
private  int stopReaderMessageID
           
private  java.util.Vector unsolicitedListeners
           
private  boolean unsolSvrShutDnNotification
           
private  java.lang.Object writeSemaphore
           
private  int writeSemaphoreCount
           
private  int writeSemaphoreOwner
           
 
Constructor Summary
Connection(int timeout)
          Create a new Connection object
Connection(LDAPSocketFactory factory)
          Create a new Connection object
 
Method Summary
(package private)  int acquireWriteSemaphore()
          Acquire a simple counting semaphore that synchronizes state affecting bind.
(package private)  int acquireWriteSemaphore(int msgId)
          Acquire a simple counting semaphore that synchronizes state affecting bind.
(package private)  void addUnsolicitedNotificationListener(LDAPUnsolicitedNotificationListener listener)
          Add the specific object to the list of listeners that want to be notified when an unsolicited notification is received.
(package private)  boolean areMessagesComplete()
          This tests to see if there are any outstanding messages.
(package private)  void clearBindSemId()
          clears the writeSemaphore id used for active bind operation
(package private)  void connect(java.lang.String host, int port)
          Constructs a TCP/IP connection to a server specified in host and port.
private  void connect(java.lang.String host, int port, int semaphoreId)
          Constructs a TCP/IP connection to a server specified in host and port.
(package private)  java.lang.Object copy_timeout()
          Copy this Connection object.
(package private)  java.lang.Object copy()
          Copy this Connection object.
(package private)  Connection destroyClone(boolean apiCall)
          Destroys a clone of LDAPConnection.
protected  void finalize()
          Cleans up resources associated with this connection.
(package private)  void freeWriteSemaphore(int msgId)
          Release a simple counting semaphore that synchronizes state affecting bind.
(package private)  ReferralInfo getActiveReferral()
          Gets the current referral active on this connection if created to follow referrals.
(package private)  BindProperties getBindProperties()
          Sets the authentication credentials in the object and set flag indicating successful bind.
(package private)  int getBindSemId()
          gets the writeSemaphore id used for active bind operation
(package private)  java.lang.String getConnectionName()
          Returns the name of this Connection, used for debug only
(package private)  java.lang.String getHost()
          gets the host used for this connection
(package private)  MessageAgent getMessageAgent(int msgId)
          Returns the message agent for this msg ID
(package private)  int getPort()
          gets the port used for this connection
(package private)  LDAPSocketFactory getSocketFactory()
          gets the socket factory used for this connection
(package private)  int getSocketTimeOut()
          Gets SocketTimeOut value set.
(package private)  void incrCloneCount()
          Increments the count of cloned connections
(package private)  boolean isBindSemIdClear()
          checks if the writeSemaphore id used for active bind operation is clear
(package private)  boolean isBound()
          Return whether the application is bound to this connection.
(package private)  boolean isCloned()
          Indicates whether clones exist for LDAPConnection
(package private)  boolean isConnected()
          Return whether a connection has been made
(package private)  boolean isConnectionAlive()
          Checks whether a connection is still alive or not by sending data to the server on this connection's socket.If the connection is not alive the send will generate an IOException and the function will return false.
(package private)  boolean isTLS()
          Indicates if the connection is using TLS protection.
private  void notifyAllUnsolicitedListeners(RfcLDAPMessage message)
           
(package private)  void removeMessage(Message info)
          Removes a Message class from the Connection's list
(package private)  void removeUnsolicitedNotificationListener(LDAPUnsolicitedNotificationListener listener)
          Remove the specific object from current list of listeners
(package private)  void setActiveReferral(ReferralInfo referral)
          Sets the current referral active on this connection if created to follow referrals.
(package private)  void setBindProperties(BindProperties bindProps)
          Sets the authentication credentials in the object and set flag indicating successful bind.
(package private)  void setBindSemId(int id)
          sets the writeSemaphore id used for active bind operation
(package private) static void setSocketFactory(LDAPSocketFactory factory)
          sets the default socket factory
(package private)  void setSocketTimeOut(int timeout)
          Sets the SocketTimeOut value.
private  void shutdown(java.lang.String reason, int semaphoreId, InterThreadException notifyUser)
          Cleans up resources associated with this connection.
(package private)  void startReader()
          startReader startReader should be called when socket and io streams have been set or changed.
(package private)  void startTLS()
          StartsTLS, in this package, assumes the caller has: 1) Acquired the writeSemaphore 2) Stopped the reader thread 3) checked that no messages are outstanding on this connection.
(package private)  void stopReaderOnReply(int messageID)
          The reader thread will stop when a reply is read with an ID equal to the messageID passed in to this method.
(package private)  void stopTLS()
           
private  void waitForReader(java.lang.Thread thread)
           
(package private)  void writeMessage(LDAPMessage msg)
          Writes an LDAPMessage to the LDAP server over a socket.
(package private)  void writeMessage(Message info)
          Writes an LDAPMessage to the LDAP server over a socket.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

writeSemaphore

private java.lang.Object writeSemaphore

writeSemaphoreOwner

private int writeSemaphoreOwner

writeSemaphoreCount

private int writeSemaphoreCount

ephemeralId

private int ephemeralId

bindProperties

private BindProperties bindProperties

bindSemaphoreId

private int bindSemaphoreId

reader

private java.lang.Thread reader

deadReader

private java.lang.Thread deadReader

deadReaderException

private java.io.IOException deadReaderException

encoder

private LBEREncoder encoder

decoder

private LBERDecoder decoder

socket

private java.net.Socket socket

nonTLSBackup

private java.net.Socket nonTLSBackup

in

private java.io.InputStream in

out

private java.io.OutputStream out

clientActive

private boolean clientActive

unsolSvrShutDnNotification

private boolean unsolSvrShutDnNotification

CONTINUE_READING

private static final int CONTINUE_READING
See Also:
Constant Field Values

STOP_READING

private static final int STOP_READING
See Also:
Constant Field Values

stopReaderMessageID

private int stopReaderMessageID

messages

private MessageVector messages

activeReferral

private ReferralInfo activeReferral

unsolicitedListeners

private java.util.Vector unsolicitedListeners

socketFactory

private static LDAPSocketFactory socketFactory

mySocketFactory

private LDAPSocketFactory mySocketFactory

myTimeOut

private int myTimeOut

host

private java.lang.String host

port

private int port

cloneCount

private int cloneCount

name

private java.lang.String name

nameLock

private static java.lang.Object nameLock

connNum

private static int connNum

sdk

static java.lang.String sdk

protocol

static java.lang.Integer protocol

security

static java.lang.String security
Constructor Detail

Connection

Connection(LDAPSocketFactory factory)
Create a new Connection object

Parameters:
factory - specifies the factory to use to produce SSL sockets.

Connection

Connection(int timeout)
Create a new Connection object

Parameters:
timeout - specifies the socket timeout to be used when the server is stalled.
Method Detail

copy

java.lang.Object copy()
Copy this Connection object.

This is not a true clone, but creates a new object encapsulating part of the connection information from the original object. The new object will have the same default socket factory, designated socket factory, host, port, and protocol version as the original object. The new object is NOT be connected to the host.

Returns:
a shallow copy of this object

copy_timeout

java.lang.Object copy_timeout()
Copy this Connection object.

This is not a true clone, but creates a new object encapsulating part of the connection information from the original object. The new object will have the same default socket factory, designated socket factory, host, port, and protocol version as the original object. The new object is NOT be connected to the host.

Returns:
a shallow copy of this object

acquireWriteSemaphore

final int acquireWriteSemaphore()
Acquire a simple counting semaphore that synchronizes state affecting bind. This method generates an ephemeral message id (negative number). We bind using the message ID because a different thread may unlock the semaphore than the one that set it. It is cleared when the response to the bind is processed, or when the bind operation times out. Returns when the semaphore is acquired

Returns:
the ephemeral message id that identifies semaphore's owner

acquireWriteSemaphore

final int acquireWriteSemaphore(int msgId)
Acquire a simple counting semaphore that synchronizes state affecting bind. The semaphore is held by setting a value in writeSemaphoreOwner. We bind using the message ID because a different thread may unlock the semaphore than the one that set it. It is cleared when the response to the bind is processed, or when the bind operation times out. Returns when the semaphore is acquired.

Parameters:
msgId - a value that identifies the owner of this semaphore. A value of zero means assign a unique semaphore value.
Returns:
the semaphore value used to acquire the lock

freeWriteSemaphore

final void freeWriteSemaphore(int msgId)
Release a simple counting semaphore that synchronizes state affecting bind. Frees the semaphore when number of acquires and frees for this thread match.

Parameters:
msgId - a value that identifies the owner of this semaphore

waitForReader

private void waitForReader(java.lang.Thread thread)
                    throws LDAPException
Throws:
LDAPException

connect

void connect(java.lang.String host,
             int port)
       throws LDAPException
Constructs a TCP/IP connection to a server specified in host and port.

Parameters:
host - The host to connect to.

port - The port on the host to connect to.
Throws:
LDAPException

connect

private void connect(java.lang.String host,
                     int port,
                     int semaphoreId)
              throws LDAPException
Constructs a TCP/IP connection to a server specified in host and port. Starts the reader thread.

Parameters:
host - The host to connect to.

port - The port on the host to connect to.

semaphoreId - The write semaphore ID to use for the connect
Throws:
LDAPException

isCloned

final boolean isCloned()
Indicates whether clones exist for LDAPConnection

Returns:
true if clones exist, false otherwise.

incrCloneCount

final void incrCloneCount()
Increments the count of cloned connections


destroyClone

final Connection destroyClone(boolean apiCall)
Destroys a clone of LDAPConnection.

This method first determines if only one LDAPConnection object is associated with this connection, i.e. if no clone exists.

If no clone exists, the socket is closed, and the current Connection object is returned.

If multiple LDAPConnection objects are associated with this connection, i.e. clones exist, a copy() of the this object is made, but is not connected to any host. This disassociates that clone from the original connection. The new Connection object is returned.

Only one destroyClone instance is allowed to run at any one time.

If the connection is closed, any threads waiting for operations on that connection will wake with an LDAPException indicating the connection is closed.

Parameters:
apiCall - true indicates the application is closing the connection or or creating a new one by calling either the connect or disconnect methods of LDAPConnection. false indicates that LDAPConnection is being finalized.
Returns:
a Connection object or null if finalizing.

setSocketFactory

static final void setSocketFactory(LDAPSocketFactory factory)
sets the default socket factory

Parameters:
factory - the default factory to set

getSocketFactory

final LDAPSocketFactory getSocketFactory()
gets the socket factory used for this connection

Returns:
the default factory for this connection

getHost

final java.lang.String getHost()
gets the host used for this connection


getPort

final int getPort()
gets the port used for this connection


getBindSemId

int getBindSemId()
gets the writeSemaphore id used for active bind operation


setBindSemId

void setBindSemId(int id)
sets the writeSemaphore id used for active bind operation


clearBindSemId

void clearBindSemId()
clears the writeSemaphore id used for active bind operation


getSocketTimeOut

final int getSocketTimeOut()
Gets SocketTimeOut value set. If not set, returns 0.


setSocketTimeOut

final void setSocketTimeOut(int timeout)
Sets the SocketTimeOut value.


isBindSemIdClear

boolean isBindSemIdClear()
checks if the writeSemaphore id used for active bind operation is clear


writeMessage

void writeMessage(Message info)
            throws LDAPException
Writes an LDAPMessage to the LDAP server over a socket.

Parameters:
info - the Message containing the message to write.
Throws:
LDAPException

writeMessage

void writeMessage(LDAPMessage msg)
            throws LDAPException
Writes an LDAPMessage to the LDAP server over a socket.

Parameters:
msg - the message to write.
Throws:
LDAPException

getMessageAgent

final MessageAgent getMessageAgent(int msgId)
                            throws java.lang.NoSuchFieldException
Returns the message agent for this msg ID

Throws:
java.lang.NoSuchFieldException

isBound

final boolean isBound()
Return whether the application is bound to this connection. Note: an anonymous bind returns false - not bound


isConnected

final boolean isConnected()
Return whether a connection has been made


isConnectionAlive

final boolean isConnectionAlive()
Checks whether a connection is still alive or not by sending data to the server on this connection's socket.If the connection is not alive the send will generate an IOException and the function will return false.

Returns:
true If connection is alive false If connection is not alive.

removeMessage

final void removeMessage(Message info)
Removes a Message class from the Connection's list

Parameters:
info - the Message class to remove from the list

finalize

protected void finalize()
Cleans up resources associated with this connection.

Overrides:
finalize in class java.lang.Object

shutdown

private void shutdown(java.lang.String reason,
                      int semaphoreId,
                      InterThreadException notifyUser)
Cleans up resources associated with this connection. This method may be called by finalize() for the connection, or it may be called by LDAPConnection.disconnect(). Should not have a writeSemaphore lock in place, as deadlock can occur while abandoning connections.


setBindProperties

final void setBindProperties(BindProperties bindProps)
Sets the authentication credentials in the object and set flag indicating successful bind.

Parameters:
bindProps - The BindProperties object to set.

getBindProperties

final BindProperties getBindProperties()
Sets the authentication credentials in the object and set flag indicating successful bind.

Returns:
The BindProperties object for this connection.

areMessagesComplete

final boolean areMessagesComplete()
This tests to see if there are any outstanding messages. If no messages are in the queue it returns true. Each message will be tested to verify that it is complete. The writeSemaphore must be set for this method to be reliable!

Returns:
true if no outstanding messages

stopReaderOnReply

final void stopReaderOnReply(int messageID)
The reader thread will stop when a reply is read with an ID equal to the messageID passed in to this method. This is used by LDAPConnection.StartTLS.


startReader

final void startReader()
                throws LDAPException
startReader startReader should be called when socket and io streams have been set or changed. In particular after client.Connection.startTLS() It assumes the reader thread is not running.

Throws:
LDAPException

isTLS

final boolean isTLS()
Indicates if the connection is using TLS protection. Returns true if using TLS protection.


startTLS

final void startTLS()
             throws LDAPException
StartsTLS, in this package, assumes the caller has: 1) Acquired the writeSemaphore 2) Stopped the reader thread 3) checked that no messages are outstanding on this connection. After calling this method upper layers should start the reader by calling startReader() In the client.Connection, StartTLS assumes LDAP.LDAPConnection will stop and start the reader thread. Connection.StopTLS will stop and start the reader thread.

Throws:
LDAPException

stopTLS

final void stopTLS()
            throws LDAPException
Throws:
LDAPException

setActiveReferral

final void setActiveReferral(ReferralInfo referral)
Sets the current referral active on this connection if created to follow referrals.


getActiveReferral

final ReferralInfo getActiveReferral()
Gets the current referral active on this connection if created to follow referrals.

Returns:
the active referral url

addUnsolicitedNotificationListener

final void addUnsolicitedNotificationListener(LDAPUnsolicitedNotificationListener listener)
Add the specific object to the list of listeners that want to be notified when an unsolicited notification is received.


removeUnsolicitedNotificationListener

final void removeUnsolicitedNotificationListener(LDAPUnsolicitedNotificationListener listener)
Remove the specific object from current list of listeners


notifyAllUnsolicitedListeners

private void notifyAllUnsolicitedListeners(RfcLDAPMessage message)

getConnectionName

java.lang.String getConnectionName()
Returns the name of this Connection, used for debug only

Returns:
the name of this connection

All LDAP Classes
Internal LDAP Classes

Copyright ? 2002 Novell, Inc. All Rights Reserved.
Novell, Inc.
1800 South Novell Place
Provo, Ut 84606
Phone: (801) 861-5000