Package 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 anEntrySource
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 theperson
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 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
All Methods Instance Methods Concrete Methods Modifier and Type Method 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.
-
-
-
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 benull
.searchRequest
- The search request that will be used to identify which entries should be returned. It must not benull
, and it must not be configured with aSearchResultListener
.closeConnection
- Indicates whether the provided connection should be closed whenever all of the entries have been read, or if theclose()
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 benull
.searchRequest
- The search request that will be used to identify which entries should be returned. It must not benull
, and it must not be configured with aSearchResultListener
.closeConnection
- Indicates whether the provided connection should be closed whenever all of the entries have been read, or if theclose()
method is called.queueSize
- The size of the internal queue used to hold search result entries until they can be consumed by thenextEntry()
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 classEntrySource
- 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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Specified by:
close
in classEntrySource
-
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 anull
return value from thenextEntry()
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 interfaceSearchResultListener
- 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 interfaceSearchResultListener
- 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 interfaceAsyncSearchResultListener
- Parameters:
requestID
- The async request ID of the request for which the response was received.searchResult
- The search result that has been received.
-
-