netscape.ldap
Class LDAPResponseListener

java.lang.Object
  extended bynetscape.ldap.LDAPMessageQueue
      extended bynetscape.ldap.LDAPResponseListener
All Implemented Interfaces:
java.io.Serializable

public class LDAPResponseListener
extends LDAPMessageQueue

Represents the message queue associated with a particular LDAP operation or operations.

See Also:
Serialized Form

Field Summary
(package private) static long serialVersionUID
           
 
Constructor Summary
(package private) LDAPResponseListener(boolean asynchOp)
          Constructor
 
Method Summary
(package private)  void addMessage(LDAPMessage msg)
          Queues the LDAP server's response.
(package private)  void addRequest(int id, LDAPConnection connection, LDAPConnThread connThread, int timeLimit)
          Registers a LDAP request
(package private)  LDAPResponse completeRequest()
          Wait for request to complete.
(package private)  java.util.Vector getAllMessages()
          Retrieves all messages currently in the queue without blocking
(package private)  LDAPConnection getConnection(int id)
          Returns the connection associated with the specified request id
(package private)  LDAPConnThread getConnThread(int id)
          Returns the connection thread associated with the specified request id
 int getMessageCount()
          Returns the count of queued messages
(package private)  int getMessageID()
          Returns message ID of the last request
 int[] getMessageIDs()
          Returns message IDs for all outstanding requests
 int getRequestCount()
          Returns the number of outstanding requests.
 LDAPResponse getResponse()
          Blocks until a response is available, or until all operations associated with the object have completed or been canceled, and returns the response.
(package private)  boolean isAsynchOp()
          Returns a flag whether the listener is used for asynchronous LDAP operations
(package private)  boolean isMessageReceived()
          Checks if response message is received.
 boolean isResponseReceived()
          Reports true if a response has been received from the server.
(package private)  void merge(LDAPMessageQueue mq2)
          Merge two message queues.
 void merge(LDAPResponseListener listener2)
          Merge two response listeners.
(package private)  LDAPMessage nextMessage()
          Blocks until a response is available or until all operations associated with the object have completed or been canceled.
(package private)  int removeAllRequests(LDAPConnThread connThread)
          Remove all requests associated with the specified connThread Called when a connThread has a network error
(package private)  boolean removeRequest(int id)
          Remove request with the specified ID Called when a LDAP operation is abandoned (called from LDAPConnThread), or terminated (called by nextMessage() when LDAPResponse message is received)
(package private)  void reset()
          Resets the state of this object, so it can be recycled.
(package private)  void setException(LDAPConnThread connThread, LDAPException e)
          Signals that a network exception occured while servicing the request.
 java.lang.String toString()
          String representation of the object
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID

static final long serialVersionUID
See Also:
Constant Field Values
Constructor Detail

LDAPResponseListener

LDAPResponseListener(boolean asynchOp)
Constructor

Parameters:
asynchOp - a boolean flag that is true if the object is used for asynchronous LDAP operations
See Also:
LDAPAsynchronousConnection
Method Detail

getResponse

public LDAPResponse getResponse()
                         throws LDAPException
Blocks until a response is available, or until all operations associated with the object have completed or been canceled, and returns the response.

Returns:
a response for an LDAP operation or null if there are no more outstanding requests.
Throws:
LDAPException - Network error exception
LDAPInterruptedException - The invoking thread was interrupted

merge

public void merge(LDAPResponseListener listener2)
Merge two response listeners. Move/append the content from another response listener to this one.

To be used for synchronization of asynchronous LDAP operations where requests are sent by one thread but processed by another one.

A client may be implemented in such a way that one thread makes LDAP requests and calls l.getMessageIDs(), while another thread is responsible for processing of responses (call l.getResponse()). Both threads are using the same listener objects. In such a case, a race condition may occur, where a LDAP response message is retrieved and the request terminated (request ID removed) before the first thread has a chance to execute l.getMessageIDs(). The proper way to handle this scenario is to create a separate listener for each new request, and after l.getMessageIDs() has been invoked, merge the new request with the existing one.

Parameters:
listener2 - the listener with which to merge

isResponseReceived

public boolean isResponseReceived()
Reports true if a response has been received from the server.

Returns:
a flag indicating whether the response message queue is empty.

getMessageIDs

public int[] getMessageIDs()
Returns message IDs for all outstanding requests

Overrides:
getMessageIDs in class LDAPMessageQueue
Returns:
message ID array.

isAsynchOp

boolean isAsynchOp()
Returns a flag whether the listener is used for asynchronous LDAP operations

Returns:
asynchronous operation flag.
See Also:
LDAPAsynchronousConnection

nextMessage

LDAPMessage nextMessage()
                  throws LDAPException
Blocks until a response is available or until all operations associated with the object have completed or been canceled.

Returns:
LDAP message or null if there are no more outstanding requests.
Throws:
LDAPException - Network error exception
LDAPInterruptedException - The invoking thread was interrupted

completeRequest

LDAPResponse completeRequest()
                       throws LDAPException
Wait for request to complete. This method blocks until a message of type LDAPResponse has been received. Used by synchronous search with batch size of zero (block until all results are received)

Returns:
LDAPResponse message or null if there are no more outstanding requests.
Throws:
LDAPException - Network error exception
LDAPInterruptedException - The invoking thread was interrupted

merge

void merge(LDAPMessageQueue mq2)
Merge two message queues. Move/append the content from another message queue to this one. To be used for synchronization of asynchronous LDAP operations where requests are sent by one thread but processed by another one A client may be implemented in such a way that one thread makes LDAP requests and calls l.getMessageIDs(), while another thread is responsible for processing of responses (call l.getResponse()). Both threads are using the same listener objects. In such a case, a race condition may occur, where a LDAP response message is retrieved and the request terminated (request ID removed) before the first thread has a chance to execute l.getMessageIDs(). The proper way to handle this scenario is to create a separate listener for each new request, and after l.getMessageIDs() has been invoked, merge the new request with the existing one.

Parameters:
mq2 - message queue to merge with this one

getAllMessages

java.util.Vector getAllMessages()
Retrieves all messages currently in the queue without blocking

Returns:
vector of messages.

addMessage

void addMessage(LDAPMessage msg)
Queues the LDAP server's response. This causes anyone waiting in nextMessage() to unblock.

Parameters:
msg - response message

setException

void setException(LDAPConnThread connThread,
                  LDAPException e)
Signals that a network exception occured while servicing the request. This exception will be throw to any thread waiting in nextMessage()

Parameters:
connThread - LDAPConnThread on which the exception occurred
e - exception

isMessageReceived

boolean isMessageReceived()
Checks if response message is received.

Returns:
true or false.

getMessageCount

public int getMessageCount()
Returns the count of queued messages

Returns:
message count.

reset

void reset()
Resets the state of this object, so it can be recycled. Used by LDAPConnection synchronous operations.

See Also:
LDAPConnection.getResponseListener(), netscape.ldap.LDAPConnection#getSearchListener

getConnection

LDAPConnection getConnection(int id)
Returns the connection associated with the specified request id

Parameters:
id - request id
Returns:
connection.

getConnThread

LDAPConnThread getConnThread(int id)
Returns the connection thread associated with the specified request id

Parameters:
id - request id.
Returns:
connection thread.

getMessageID

int getMessageID()
Returns message ID of the last request

Returns:
message ID.

addRequest

void addRequest(int id,
                LDAPConnection connection,
                LDAPConnThread connThread,
                int timeLimit)
Registers a LDAP request

Parameters:
id - LDAP request message ID
connection - LDAP Connection for the message ID
connThread - a physical connection to the server
timeLimit - the maximum number of milliseconds to wait for the request to complete

getRequestCount

public int getRequestCount()
Returns the number of outstanding requests.

Returns:
outstanding request count.

removeRequest

boolean removeRequest(int id)
Remove request with the specified ID Called when a LDAP operation is abandoned (called from LDAPConnThread), or terminated (called by nextMessage() when LDAPResponse message is received)

Returns:
flag indicating whether the request was removed.

removeAllRequests

int removeAllRequests(LDAPConnThread connThread)
Remove all requests associated with the specified connThread Called when a connThread has a network error

Returns:
number of removed requests.

toString

public java.lang.String toString()
String representation of the object