public class ConnectionEntryReader extends Object implements EntryReader
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 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.
|
| 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.
|
public ConnectionEntryReader(Connection connection, SearchRequest searchRequest)
LinkedBlockingQueue.connection - The connection to use.searchRequest - The search request to retrieve entries with.NullPointerException - If connection was null.public ConnectionEntryReader(Connection connection, SearchRequest searchRequest, BlockingQueue<Response> entries)
connection - The connection to use.searchRequest - The search request to retrieve entries with.entries - The BlockingQueue implementation to use when queuing
the returned entries.NullPointerException - If connection was null.public void close()
close in interface Closeableclose in interface AutoCloseableclose in interface EntryReaderpublic boolean hasNext() throws LdapException
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.hasNext in interface EntryReadertrue if this reader contains another entry.LdapExceptionpublic boolean isEntry() throws LdapException
true if it is an entry, or false if it is a
reference.true if the next search result is an entry, or
false if it is a reference.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.public boolean isReference() throws LdapException
true if it is a reference, or false if it is
an entry.true if the next search result is a reference, or
false if it is an entry.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.public SearchResultEntry readEntry() throws SearchResultReferenceIOException, LdapException
SearchResultEntry. If the
next search response is a reference then this method will throw a
SearchResultReferenceIOException.readEntry in interface EntryReaderSearchResultReferenceIOException - 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.public SearchResultReference readReference() throws LdapException
SearchResultReference.
If the next search response is an entry then this method will return
null.null if the next
response was a search result entry.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.public Result readResult() throws LdapException
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.
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.Copyright © 2011-2015 ForgeRock AS. All Rights Reserved.