netscape.ldap
Class LDAPSearchListener

java.lang.Object
  extended by netscape.ldap.LDAPMessageQueue
      extended by netscape.ldap.LDAPSearchListener
All Implemented Interfaces:
java.io.Serializable

public class LDAPSearchListener
extends LDAPMessageQueue

Manages search results, references and responses returned on one or more search requests

See Also:
Serialized Form

Field Summary
(package private) static long serialVersionUID
           
 
Constructor Summary
LDAPSearchListener(boolean asynchOp, LDAPSearchConstraints cons)
          Constructs a LDAP search listener.
 
Method Summary
(package private)  LDAPResponse completeSearchOperation()
          Block until all results are in.
(package private)  java.lang.Long getKey()
          Get the key of the cache entry.
 int[] getMessageIDs()
          Returns message IDs for all outstanding requests
 LDAPMessage getResponse()
          Blocks until a search result, reference or response is available, or until all operations associated with the object have completed or been canceled.
(package private)  LDAPSearchConstraints getSearchConstraints()
          Return the search constraints used to create this object.
 boolean isResponseReceived()
          Reports true if a response has been received from the server.
 void merge(LDAPSearchListener listener2)
          Merge two response listeners.
(package private)  LDAPMessage nextMessage()
          Override nextMessage to wake up the LDAPConnThread if backlog limit has been reached
(package private)  void reset()
          Resets the state of this object, so it can be recycled.
(package private)  void setKey(java.lang.Long key)
          Set the key of the cache entry.
(package private)  void setSearchConstraints(LDAPSearchConstraints cons)
          Set new search constraints object.
 
Methods inherited from class netscape.ldap.LDAPMessageQueue
addMessage, addRequest, completeRequest, getAllMessages, getConnection, getConnThread, getMessageCount, getMessageID, getRequestCount, isAsynchOp, isMessageReceived, merge, removeAllRequests, removeRequest, setException, toString, waitFirstMessage
 
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

LDAPSearchListener

LDAPSearchListener(boolean asynchOp,
                   LDAPSearchConstraints cons)
Constructs a LDAP search listener.

Parameters:
asynchOp - a boolean flag indicating whether the object is used for asynchronous LDAP operations
cons - LDAP search constraints
See Also:
LDAPAsynchronousConnection
Method Detail

completeSearchOperation

LDAPResponse completeSearchOperation()
                               throws LDAPException
Block until all results are in. Used for synchronous search with batch size of zero.

Returns:
search response message.
Throws:
Network - exception error
LDAPException

getResponse

public LDAPMessage getResponse()
                        throws LDAPException
Blocks until a search result, reference or response is available, or until all operations associated with the object have completed or been canceled.

Returns:
a search result, search reference, search response message, or null if there are no more outstanding requests.
Throws:
LDAPException - Network error exception
LDAPInterruptedException - The invoking thread was interrupted
See Also:
LDAPResponse, LDAPSearchResult, LDAPSearchResultReference

nextMessage

LDAPMessage nextMessage()
                  throws LDAPException
Override nextMessage to wake up the LDAPConnThread if backlog limit has been reached

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

merge

public void merge(LDAPSearchListener 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.

getSearchConstraints

LDAPSearchConstraints getSearchConstraints()
Return the search constraints used to create this object.

Returns:
the search constraints used to create this object.

setSearchConstraints

void setSearchConstraints(LDAPSearchConstraints cons)
Set new search constraints object.

Parameters:
cons - LDAP search constraints

reset

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

Overrides:
reset in class LDAPMessageQueue
See Also:
LDAPConnection.getResponseListener(), LDAPConnection.getSearchListener(netscape.ldap.LDAPSearchConstraints)

setKey

void setKey(java.lang.Long key)
Set the key of the cache entry. The listener needs to know this value when the results get processed in the queue. After the results have been saved in the vector, then the key and a vector of results are put in the cache.

Parameters:
key - the key of the cache entry

getKey

java.lang.Long getKey()
Get the key of the cache entry.

Returns:
the key of the cache entry.