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 and 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 and 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 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 Closeable

Specified by:

close in interface AutoCloseable

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 ConnectionEntryReader.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 ConnectionEntryReader.hasNext() would return true.