Class 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
    • 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.
      • 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.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        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.
      • 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.