Class EntrySource

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    Direct Known Subclasses:
    DNEntrySource, LDAPEntrySource, LDIFEntrySource

    @NotExtensible
    @ThreadSafety(level=INTERFACE_NOT_THREADSAFE)
    public abstract class EntrySource
    extends java.lang.Object
    implements java.io.Closeable
    This class defines an API that may be implemented by a class that provides access to a sequence of entries, one entry at a time (e.g., entries read from an LDIF file, or returned as part of an LDAP search). It provides a convenient way to operate on a set of entries without regard for the source of those entries. Implementations currently available include the LDAPEntrySource class, which can be used to iterate across entries returned from a directory server in response to a search request, and the LDIFEntrySource class, which can be used to iterate across entries in an LDIF file.

    Note that the close() method MUST be called if the entry source is to be discarded before guaranteeing that all entries have been read. The close method may be called after all entries have been read, but it is not required. All entry source implementations MUST ensure that all resources are properly released if the caller has read through all entries, or if an error occurs that prevents the caller from continuing to read through the entries (i.e., if nextEntry() throws an EntrySourceException and the EntrySourceException.mayContinueReading() method returns false).

    Example

    The following example demonstrates the process that may be used for iterating across the entries provided by an entry source:
     LDIFReader ldifReader = new LDIFReader(ldifFilePath);
     EntrySource entrySource = new LDIFEntrySource(ldifReader);
    
     int entriesRead = 0;
     int exceptionsCaught = 0;
     try
     {
       while (true)
       {
         try
         {
           Entry entry = entrySource.nextEntry();
           if (entry == null)
           {
             // There are no more entries to be read.
             break;
           }
           else
           {
             // Do something with the entry here.
             entriesRead++;
           }
         }
         catch (EntrySourceException e)
         {
           // Some kind of problem was encountered (e.g., a malformed entry
           // found in an LDIF file, or a referral returned from a directory).
           // See if we can continue reading entries.
           exceptionsCaught++;
           if (! e.mayContinueReading())
           {
             break;
           }
         }
       }
     }
     finally
     {
       entrySource.close();
     }
     
    • Constructor Summary

      Constructors 
      Constructor Description
      EntrySource()  
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      abstract void close()
      Indicates that this entry source will no longer be needed and any resources associated with it may be closed.
      abstract 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
    • Method Detail

      • nextEntry

        @Nullable
        public abstract 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.
        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 abstract 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.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable