com.unboundid.ldap.sdk

Class LDAPEntrySource

java.lang.Object

com.unboundid.ldap.sdk.EntrySource

com.unboundid.ldap.sdk.LDAPEntrySource

All Implemented Interfaces:

AsyncSearchResultListener, SearchResultListener, java.io.Closeable, java.io.Serializable, java.lang.AutoCloseable

@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:

• It makes it easier to provide a throttling mechanism to prevent the entries from piling up and causing the client to run out of memory if the server returns them faster than the client can process them. If this occurs, then the client will queue up a small number of entries but will then push back against the server to block it from sending additional entries until the client can catch up. In this case, no entries should be lost, although some servers may impose limits on how long a search may be active or other forms of constraints.
• It makes it possible to abandon the search if the entry source is no longer needed (as signified by calling the close() method) and the caller intends to stop iterating through the results.

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

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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(@NotNull
                       LDAPConnection connection,
                       @NotNull
                       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(@NotNull
                       LDAPConnection connection,
                       @NotNull
                       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

@Nullable
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 interface java.lang.AutoCloseable

Specified by:

close in class EntrySource

getSearchResult

@Nullable
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(@NotNull
                                                 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(@NotNull
                                                     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(@NotNull
                                                  AsyncRequestID requestID,
                                                  @NotNull
                                                  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.