com.unboundid.ldap.sdk

Class DNEntrySource

java.lang.Object

com.unboundid.ldap.sdk.EntrySource

com.unboundid.ldap.sdk.DNEntrySource

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

@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

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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(@NotNull
                     LDAPInterface connection,
                     @NotNull
                     DN[] dns,
                     @Nullable
                     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(@NotNull
                     LDAPInterface connection,
                     @NotNull
                     java.lang.String[] dns,
                     @Nullable
                     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(@NotNull
                     LDAPInterface connection,
                     @NotNull
                     java.util.Collection<java.lang.String> dns,
                     @Nullable
                     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

@Nullable
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 interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in class EntrySource