com.unboundid.ldap.sdk
Class LDAPEntrySource

java.lang.Object
  extended by com.unboundid.ldap.sdk.EntrySource
      extended by com.unboundid.ldap.sdk.LDAPEntrySource
All Implemented Interfaces:
AsyncSearchResultListener, SearchResultListener, java.io.Closeable, java.io.Serializable

@ThreadSafety(level=NOT_THREADSAFE)
public final class LDAPEntrySource
extends EntrySource
implements AsyncSearchResultListener

This class provides an EntrySource that will read entries matching a given set of search criteria from an LDAP directory server. It may optionally close the associated connection after all entries have been read.

This implementation processes the search asynchronously, which provides two benefits:

Example

The following example demonstrates the process that may be used for iterating across all entries containing the person object class using the LDAP entry source API:
 SearchRequest searchRequest = new SearchRequest("dc=example,dc=com",
      SearchScope.SUB, Filter.createEqualityFilter("objectClass", "person"));
 LDAPEntrySource entrySource = new LDAPEntrySource(connection,
      searchRequest, false);

 int entriesRead = 0;
 int referencesRead = 0;
 int exceptionsCaught = 0;
 try
 {
   while (true)
   {
     try
     {
       Entry entry = entrySource.nextEntry();
       if (entry == null)
       {
         // There are no more entries to be read.
         break;
       }
       else
       {
         // Do something with the entry here.
         entriesRead++;
       }
     }
     catch (SearchResultReferenceEntrySourceException e)
     {
       // The directory server returned a search result reference.
       SearchResultReference searchReference = e.getSearchReference();
       referencesRead++;
     }
     catch (EntrySourceException e)
     {
       // Some kind of problem was encountered (e.g., the connection is no
       // longer valid).  See if we can continue reading entries.
       exceptionsCaught++;
       if (! e.mayContinueReading())
       {
         break;
       }
     }
   }
 }
 finally
 {
   entrySource.close();
 }
 

See Also:
Serialized Form

Constructor Summary
LDAPEntrySource(LDAPConnection connection, SearchRequest searchRequest, boolean closeConnection)
          Creates a new LDAP entry source with the provided information.
LDAPEntrySource(LDAPConnection connection, SearchRequest searchRequest, boolean closeConnection, int queueSize)
          Creates a new LDAP entry source with the provided information.
 
Method Summary
 void close()
          Indicates that this entry source will no longer be needed and any resources associated with it may be closed.
 SearchResult getSearchResult()
          Retrieves the search result for the search operation, if available.
 Entry nextEntry()
          Retrieves the next entry from the entry source, if there is at least one remaining entry.
 void searchEntryReturned(SearchResultEntry searchEntry)
          Indicates that the provided search result entry has been returned by the server and may be processed by this search result listener.
 void searchReferenceReturned(SearchResultReference searchReference)
          Indicates that the provided search result reference has been returned by the server and may be processed by this search result listener.
 void searchResultReceived(AsyncRequestID requestID, SearchResult searchResult)
          Indicates that the provided search result has been received in response to an asynchronous search operation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LDAPEntrySource

public LDAPEntrySource(LDAPConnection connection,
                       SearchRequest searchRequest,
                       boolean closeConnection)
                throws LDAPException
Creates a new LDAP entry source with the provided information.

Parameters:
connection - The connection to the directory server from which the entries will be read. It must not be null.
searchRequest - The search request that will be used to identify which entries should be returned. It must not be null, and it must not be configured with a SearchResultListener.
closeConnection - Indicates whether the provided connection should be closed whenever all of the entries have been read, or if the close() method is called.
Throws:
LDAPException - If there is a problem with the provided search request or when trying to communicate with the directory server over the provided connection.

LDAPEntrySource

public LDAPEntrySource(LDAPConnection connection,
                       SearchRequest searchRequest,
                       boolean closeConnection,
                       int queueSize)
                throws LDAPException
Creates a new LDAP entry source with the provided information.

Parameters:
connection - The connection to the directory server from which the entries will be read. It must not be null.
searchRequest - The search request that will be used to identify which entries should be returned. It must not be null, and it must not be configured with a SearchResultListener.
closeConnection - Indicates whether the provided connection should be closed whenever all of the entries have been read, or if the close() method is called.
queueSize - The size of the internal queue used to hold search result entries until they can be consumed by the nextEntry() method. The value must be greater than zero.
Throws:
LDAPException - If there is a problem with the provided search request or when trying to communicate with the directory server over the provided connection.
Method Detail

nextEntry

public Entry nextEntry()
                throws EntrySourceException
Retrieves the next entry from the entry source, if there is at least one remaining entry. This method may block if no entries are immediately available.

Specified by:
nextEntry in class EntrySource
Returns:
The next entry from the entry source, or null if there are no more entries to retrieve..
Throws:
EntrySourceException - If a problem occurs while attempting to read the next entry from the entry source.

close

public void close()
Indicates that this entry source will no longer be needed and any resources associated with it may be closed. This method MUST be called if the entry source is no longer needed before all entries have been read. It MAY be called after all entries have been read with no ill effects, but this is not necessary as the entry source will have already been closed after all entries have been read.

Specified by:
close in interface java.io.Closeable
Specified by:
close in class EntrySource

getSearchResult

public SearchResult getSearchResult()
Retrieves the search result for the search operation, if available. It will not be available until the search has completed (as indicated by a null return value from the nextEntry() method).

Returns:
The search result for the search operation, or null if it is not available (e.g., because the search has not yet completed).

searchEntryReturned

@InternalUseOnly
public void searchEntryReturned(SearchResultEntry searchEntry)
Indicates that the provided search result entry has been returned by the server and may be processed by this search result listener. This is intended for internal use only and should not be called by anything outside of the LDAP SDK itself.

Specified by:
searchEntryReturned in interface SearchResultListener
Parameters:
searchEntry - The search result entry that has been returned by the server.

searchReferenceReturned

@InternalUseOnly
public void searchReferenceReturned(SearchResultReference searchReference)
Indicates that the provided search result reference has been returned by the server and may be processed by this search result listener. This is intended for internal use only and should not be called by anything outside of the LDAP SDK itself.

Specified by:
searchReferenceReturned in interface SearchResultListener
Parameters:
searchReference - The search result reference that has been returned by the server.

searchResultReceived

@InternalUseOnly
public void searchResultReceived(AsyncRequestID requestID,
                                                 SearchResult searchResult)
Indicates that the provided search result has been received in response to an asynchronous search operation. Note that automatic referral following is not supported for asynchronous operations, so it is possible that this result could include a referral. This is intended for internal use only and should not be called by anything outside of the LDAP SDK itself.

Specified by:
searchResultReceived in interface AsyncSearchResultListener
Parameters:
requestID - The async request ID of the request for which the response was received.
searchResult - The search result that has been received.