Package org.forgerock.opendj.ldif

Class ConnectionEntryReader

java.lang.Object
org.forgerock.opendj.ldif.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.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ConnectionEntryReader(Connection connection, SearchRequest searchRequest)
    Creates a new connection entry reader whose destination is the provided connection using an unbounded LinkedBlockingQueue.
    ConnectionEntryReader(Connection connection, SearchRequest searchRequest, BlockingQueue<Response> entries)
    Creates a new connection entry reader whose destination is the provided connection.

  • Method Summary

    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.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • 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 Details

    • 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.