com.unboundid.ldap.sdk
Class DNEntrySource

java.lang.Object
  extended by com.unboundid.ldap.sdk.EntrySource
      extended by com.unboundid.ldap.sdk.DNEntrySource

@ThreadSafety(level=NOT_THREADSAFE)
public final class DNEntrySource
extends EntrySource

This class provides an EntrySource that will retrieve entries referenced by a provided set of DNs. The connection will remain open after all entries have been read.

It is not necessary to close this entry source when it is no longer needed, although there is no cost or penalty in doing so. Any exceptions thrown by the nextEntry() method will have the mayContinueReading value set to true.

Example

The following example demonstrates the process for retrieving a static group entry and using a DNEntrySource to iterate across the members of that group:
 Entry groupEntry =
      connection.getEntry("cn=My Group,ou=Groups,dc=example,dc=com");
 String[] memberValues = groupEntry.getAttributeValues("member");
 int entriesReturned = 0;
 int exceptionsCaught = 0;

 if (memberValues != null)
 {
   DNEntrySource entrySource =
        new DNEntrySource(connection, memberValues, "cn");
   try
   {
     while (true)
     {
       Entry memberEntry;
       try
       {
         memberEntry = entrySource.nextEntry();
       }
       catch (EntrySourceException ese)
       {
         // A problem was encountered while attempting to obtain an entry.
         // We may be able to continue reading entries (e.g., if the problem
         // was that the group referenced an entry that doesn't exist), or
         // we may not (e.g., if the problem was a significant search error
         // or problem with the connection).
         exceptionsCaught++;
         if (ese.mayContinueReading())
         {
           continue;
         }
         else
         {
           break;
         }
       }

       if (memberEntry == null)
       {
         // We've retrieved all of the entries for the given set of DNs.
         break;
       }
       else
       {
         entriesReturned++;
       }
     }
   }
   finally
   {
     entrySource.close();
   }
 }
 


Constructor Summary
DNEntrySource(LDAPInterface connection, java.util.Collection<java.lang.String> dns, java.lang.String... attributes)
          Creates a new DN entry source with the provided information.
DNEntrySource(LDAPInterface connection, DN[] dns, java.lang.String... attributes)
          Creates a new DN entry source with the provided information.
DNEntrySource(LDAPInterface connection, java.lang.String[] dns, java.lang.String... attributes)
          Creates a new DN entry source with the provided information.
 
Method Summary
 void close()
          Indicates that this entry source will no longer be needed and any resources associated with it may be closed.
 Entry nextEntry()
          Retrieves the next entry from the entry source, if there is at least one remaining entry.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DNEntrySource

public DNEntrySource(LDAPInterface connection,
                     DN[] dns,
                     java.lang.String... attributes)
Creates a new DN 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.
dns - The set of DNs to be read. It must not be null.
attributes - The set of attributes to include in entries that are returned. If this is empty or null, then all user attributes will be requested.

DNEntrySource

public DNEntrySource(LDAPInterface connection,
                     java.lang.String[] dns,
                     java.lang.String... attributes)
Creates a new DN 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.
dns - The set of DNs to be read. It must not be null.
attributes - The set of attributes to include in entries that are returned. If this is empty or null, then all user attributes will be requested.

DNEntrySource

public DNEntrySource(LDAPInterface connection,
                     java.util.Collection<java.lang.String> dns,
                     java.lang.String... attributes)
Creates a new DN 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.
dns - The set of DNs to be read. It must not be null.
attributes - The set of attributes to include in entries that are returned. If this is empty or null, then all user attributes will be requested.
Method Detail

nextEntry

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 class EntrySource