Package org.forgerock.opendj.ldif

Class ConnectionEntryReader

  • All Implemented Interfaces:
    Closeable, AutoCloseable, EntryReader
    public class ConnectionEntryReader
extends Object
implements EntryReader
    A ConnectionEntryReader is a bridge from Connections to EntryReaders. A connection entry reader allows applications to iterate over search results as they are returned from the server during a search operation.

    The Search operation is performed synchronously, blocking until a search result entry is received. If a search result indicates that the search operation has failed for some reason then the error result is propagated to the caller using an LdapException. If a search result reference is returned then it is propagated to the caller using a SearchResultReferenceIOException.

    The following code illustrates how a ConnectionEntryReader may be used: 

     Connection connection = ...;
 ConnectionEntryReader reader = connection.search("dc=example,dc=com",
     SearchScope.WHOLE_SUBTREE, "(objectClass=person)");
 try
 {
   while (reader.hasNext())
   {
     if (reader.isEntry())
     {
       SearchResultEntry entry = reader.readEntry();

       // Handle entry...
     }
     else
     {
       SearchResultReference ref = reader.readReference();

       // Handle continuation reference...
     }
   }

   Result result = reader.readResult();
   // Handle controls included with the search result...
 }
 catch (IOException e)
 {
   // Handle exceptions...
 }
 finally
 {
   reader.close();
 }
    NOTE: although this class is non-final, sub-classing is not supported except when creating mock objects for unit tests. This class has been selected specifically because it is the only aspect of the Connection interface which is not mockable.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Closes this connection entry reader, canceling the search request if it is still active.
      boolean hasNext()
      Returns true if this reader contains another entry, blocking if necessary until either the next entry is available or the end of the stream is reached.
      boolean isEntry()
      Waits for the next search result entry or reference to become available and returns true if it is an entry, or false if it is a reference.
      boolean isReference()
      Waits for the next search result entry or reference to become available and returns true if it is a reference, or false if it is an entry.
      SearchResultEntry readEntry()
      Waits for the next search result entry or reference to become available and, if it is an entry, returns it as a SearchResultEntry.
      SearchResultReference readReference()
      Waits for the next search result entry or reference to become available and, if it is a reference, returns it as a SearchResultReference.
      Result readResult()
      Waits for the next search response to become available and returns it if it is a search result indicating that the search completed successfully.

    • Constructor Detail

      • ConnectionEntryReader

        public ConnectionEntryReader​(Connection connection,
                             SearchRequest searchRequest)
        Creates a new connection entry reader whose destination is the provided connection using an unbounded LinkedBlockingQueue.
        Parameters:
        connection - The connection to use.
        searchRequest - The search request to retrieve entries with.
        Throws:
        NullPointerException - If connection was null.

      • ConnectionEntryReader

        public ConnectionEntryReader​(Connection connection,
                             SearchRequest searchRequest,
                             BlockingQueue<Response> entries)
        Creates a new connection entry reader whose destination is the provided connection.
        Parameters:
        connection - The connection to use.
        searchRequest - The search request to retrieve entries with.
        entries - The BlockingQueue implementation to use when queuing the returned entries.
        Throws:
        NullPointerException - If connection was null.

    • Method Detail

      • close

        public void close()
        Closes this connection entry reader, canceling the search request if it is still active.
        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Closeable
        Specified by:
        close in interface EntryReader

      • hasNext

        public boolean hasNext()
                throws LdapException
        Description copied from interface: EntryReader
        Returns true if this reader contains another entry, blocking if necessary until either the next entry is available or the end of the stream is reached.
        Specified by:
        hasNext in interface EntryReader
        Returns:
        true if this reader contains another entry.
        Throws:
        LdapException

      • isEntry

        public boolean isEntry()
                throws LdapException
        Waits for the next search result entry or reference to become available and returns true if it is an entry, or false if it is a reference.
        Returns:
        true if the next search result is an entry, or false if it is a reference.
        Throws:
        LdapException - If there are no more search result entries or references and the search result code indicates that the search operation failed for some reason.
        NoSuchElementException - If there are no more search result entries or references and the search result code indicates that the search operation succeeded.

      • isReference

        public boolean isReference()
                    throws LdapException
        Waits for the next search result entry or reference to become available and returns true if it is a reference, or false if it is an entry.
        Returns:
        true if the next search result is a reference, or false if it is an entry.
        Throws:
        LdapException - If there are no more search result entries or references and the search result code indicates that the search operation failed for some reason.
        NoSuchElementException - If there are no more search result entries or references and the search result code indicates that the search operation succeeded.

      • readEntry

        public SearchResultEntry readEntry()
                            throws SearchResultReferenceIOException,
                                   LdapException
        Waits for the next search result entry or reference to become available and, if it is an entry, returns it as a SearchResultEntry. If the next search response is a reference then this method will throw a SearchResultReferenceIOException.
        Specified by:
        readEntry in interface EntryReader
        Returns:
        The next search result entry.
        Throws:
        SearchResultReferenceIOException - If the next search response was a search result reference. This connection entry reader may still contain remaining search results and references which can be retrieved using additional calls to this method.
        LdapException - If there are no more search result entries or references and the search result code indicates that the search operation failed for some reason.
        NoSuchElementException - If there are no more search result entries or references and the search result code indicates that the search operation succeeded.

      • readReference

        public SearchResultReference readReference()
                                    throws LdapException
        Waits for the next search result entry or reference to become available and, if it is a reference, returns it as a SearchResultReference. If the next search response is an entry then this method will return null.
        Returns:
        The next search result reference, or null if the next response was a search result entry.
        Throws:
        LdapException - If there are no more search result entries or references and the search result code indicates that the search operation failed for some reason.
        NoSuchElementException - If there are no more search result entries or references and the search result code indicates that the search operation succeeded.

      • readResult

        public Result readResult()
                  throws LdapException
        Waits for the next search response to become available and returns it if it is a search result indicating that the search completed successfully. If the search result indicates that the search failed then an LdapException is thrown. Otherwise, if the search response represents an entry or reference then an IllegalStateException is thrown.

        This method should only be called if hasNext() has, or will, return false.

        It is not necessary to call this method once all search result entries have been processed, but it may be useful to do so in order to inspect any controls which were included with the result. For example, this method may be called in order to obtain the next paged results cookie once the current page of results has been processed.

        Returns:
        The search result indicating success.
        Throws:
        LdapException - If the search result indicates that the search operation failed for some reason.
        IllegalStateException - If there are remaining search result entries or references to be processed. In other words, if hasNext() would return true.