UnboundID LDAP SDK for Java

Processing Asynchronous Operations

Most LDAP clients use a synchronous model for processing requests. In this case, the client will send a request and then wait until it receives the response from the server before continuing. However, the LDAP protocol allows for asynchronous operations, in which there may be multiple concurrent requests in progress for the same connection.

There are two primary ways that the UnboundID LDAP SDK for Java can be used to process multiple operations on the same connection at the same time:

• Multiple client threads can use the same LDAPConnection object at the same time. LDAPConnection objects are threadsafe (although individual request objects are not, so the same request object should not be shared by multiple threads at the same time), so they can be used by multiple concurrent client threads as long as they conform to the requirements outlined below.
  
  
• Clients can use the asynchronous operation API provided by the UnboundID LDAP SDK for Java. In this case, the SDK will send the request to the server, but will not wait for the response to arrive before returning. The client can continue with other processing and then will be notified when the response arrives.
  
  

Note, however, that LDAP does place restrictions on asynchronous operation processing. In particular, bind operations and StartTLS operations must always be processed in a synchronous manner. If a client is going to process asynchronous operations, then it must take care to ensure that it does not attempt to process bind or StartTLS operations while other operations may be in progress.

Also note that some directory servers may enforce restrictions on the number of concurrent operations that may be in progress on a single connection at any given time, and even in cases where that is not performed it is likely the case that there may be more contention when processing concurrent operations on a single connection than if they were processed over separate connections. Therefore, it should be noted that attempting to process too many concurrent operations over a connection may have a performance impact.

The UnboundID LDAP SDK for Java provides the following methods for processing asynchronous write operations:

• public AsyncRequestID asyncAdd(AddRequest addRequest, AsyncResultListener resultListener)
  
  
• public AsyncRequestID asyncDelete(DeleteRequest deleteRequest, AsyncResultListener resultListener)
  
  
• public AsyncRequestID asyncModify(ModifyRequest modifyRequest, AsyncResultListener resultListener)
  
  
• public AsyncRequestID asyncModifyDN(ModifyDNRequest modifyDNRequest, AsyncResultListener resultListener)
  
  

Each of these methods returns an AsyncRequestID value, which is a handle that may be used to cancel or abandon the operation if desirable (see the Using Standard Extended Operations document for information about the cancel extended operation). The AsyncResultListener.ldapResultReceived method will be called whenever the SDK receives the response for the operation.

The API for processing compare operations is virtually identical to that for write operations, with the exception that the AsyncCompareResultListener.compareResultReceived method is used to provide access to the CompareResult object. The method for processing an asynchronous compare operation is:

• public AsyncRequestID asyncCompare(CompareRequest compareRequest, AsyncCompareResultListener resultListener)
  
  

There is a greater difference in the API for performing asynchronous search operations. Rather than providing a result listener as a separate argument, the given search request object must be configured with an AsyncSearchResultListener object as its SearchResultListener. The method to use to process an asynchronous search operation is:

• public AsyncRequestID asyncSearch(SearchRequest searchRequest)
  
  

The UnboundID LDAP SDK for Java does not provide support for processing bind or extended operations in an asynchronous manner. Further, it should be noted that a connection obtained from a connection pool should not be used to process asynchronous operations unless that connection is explicitly checked out of the pool and the caller is sure to wait for the response to arrive before returning the connection with the releaseConnection method, or if the response did not arrive in a timely manner then the releaseDefunctConnection method should be used to destroy the connection.