Package com.isode.dsapi.bulk

Class DirectoryScanDN

java.lang.Object
com.isode.dsapi.bulk.DirectoryScanDN
All Implemented Interfaces:
DirectoryIterator<DN>, Iterator<DN>
public class DirectoryScanDN extends Object implements DirectoryIterator<DN>
Iterate through a directory subtree, returning DNs one by one, ordered with parents immediately before children. Exceptions may be generated during the scan due to exceeding size or time limits, or due to other directory errors. These are queued, and may be requested by the caller at the end of the scan, or during the scan itself.

The scan does a one-level search at each level to avoid setting off limit errors, and uses the 'hasSubordinates' attribute, if available, to optimise the search. Paged results are used to extend the search if supported by Java-DSAPI and the directory.

The result may optionally be sorted into DN order, have an LDAP filter applied, and have arbitrary chop-points applied.

Note that there are two ways to specify an LDAP filter. With 'filter_parents' set, the filter is used not only to select the matches to return, but also to select the subtrees to follow, i.e. the filter must match the entry and all of its parents for that entry to be included in the result. With 'filter_parents' unset, the filter selects just the entries to include, and all parents are scanned (which makes it a slower operation). This is equivalent to a true LDAP subtree search, only with less risk of hitting limit errors or exceeding memory on very large/deep searches.

Note that most of the methods of this class apart from the constructor should be run only within a background thread (e.g. using BackgroundTask), as the code executes directory operations directly and will block waiting for directory operations to complete.

Author:
jp

  • Constructor Details

    • DirectoryScanDN

      public DirectoryScanDN(DirectorySession ds, DN start, int depth)
      Initialise the DirectoryScanDN to use the given directory session, start point, and depth of search. This may be run in a GUI thread.
      Parameters:
      ds - DirectorySession to use
      start - DN to start at
      depth - Depth to go below start DN (0 to return start DN only), or -1 for unlimited.

    • DirectoryScanDN

      public DirectoryScanDN(DirectorySession ds, DN start, boolean include_start, int depth, boolean sort)
      Initialise the DirectoryScanDN to use the given directory session, start point, and depth of search. This may be run in a GUI thread.
      Parameters:
      ds - DirectorySession to use
      start - DN to start at
      include_start - Include start-DN in the results?
      depth - Depth to go below start DN (0 to return start DN only), or -1 for unlimited.
      sort - Sort results into DN order?

    • DirectoryScanDN

      public DirectoryScanDN(DirectorySession ds, DN start, boolean include_start, int depth, boolean sort, String filter, boolean filter_parents, List<DN> chop_before, List<DN> chop_after)
      Initialise the DirectoryScanDN to use the given directory session, start point, depth of search, LDAP filter and before/after chop points. This may be run in a GUI thread.
      Parameters:
      ds - DirectorySession to use
      start - DN to start at
      include_start - Include start-DN in the results?
      depth - Depth to go below start DN (0 to return start DN only), or -1 for unlimited.
      sort - Sort results into DN order?
      filter - LDAP filter, or null to use no filtering
      filter_parents - If 'true' then entries and all their parents (below the starting point) must match the filter to be included in the result. If 'false', then only the entries themselves need to match, their parents are not filtered. It is more efficient if parents are filtered ('true'), but 'false' gives a result equivalent to an LDAP subtree search, which is easier for the user to specify.
      chop_before - List of chop-before DNs, or null
      chop_after - List of chop-after DNs, or null

  • Method Details

    • setPageSizes

      public void setPageSizes(int dn_page_size)
      Override the default page-size of 1000 for DN searches

    • hasNext

      public boolean hasNext()
      Check to see if there are any more DNs to be returned from this directory scan.

      This must be run from a background (non-GUI) thread as it does directory operations directly and will block whilst waiting for directory data.

      Specified by:
      hasNext in interface Iterator<DN>
      Returns:
      true if there are more DNs to be returned

    • next

      public DN next() throws NoSuchElementException
      Return the next DN from the directory search. DNs are returned ordered with parents immediately before children.

      This must be run from a background (non-GUI) thread as it does directory operations directly and will block whilst waiting for directory data.

      Specified by:
      next in interface Iterator<DN>
      Returns:
      DN instance
      Throws:
      NoSuchElementException - if the call is attempted after the last object has been returned.

    • getException

      public DirectoryIterator.ScanException getException()
      Returns the next outstanding Exception, or null if there are no more exceptions outstanding at this point in the scan. This can be called during the scan to find out problems as soon as possible, or may be checked when the scan is complete (there may be several exceptions queued by the end of the scan). The exceptions must be checked at some point, or otherwise errors may go undetected.

      The exceptions are ScanExceptions, with an explanation and the problem DN in the message text. If the exception was caused by a DSAPIException, this is available using the getCause() method. This may be called from a GUI thread.

      Specified by:
      getException in interface DirectoryIterator<DN>

    • remove

      public void remove() throws UnsupportedOperationException
      Remove operations are unsupported and generate an exception.
      Specified by:
      remove in interface Iterator<DN>
      Throws:
      UnsupportedOperationException