Class DirectoryScan

java.lang.Object
com.isode.dsapi.bulk.DirectoryScan
All Implemented Interfaces:
DirectoryIterator<Entry>, Iterator<Entry>

public class DirectoryScan extends Object implements DirectoryIterator<Entry>
Iterate through a directory subtree, returning Entry instances 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 beyond DSA size limits if supported by Java-DSAPI and the directory.

The result may optionally be sorted into DN order, have an LDAP filter applied, and also 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.

By default the returned Entry instances only contain the DN with no attributes (except perhaps 'hassubordinates' depending on the directory). However additional attributes may be requested with the addSelection() call. Note that no attributes are ever fetched for the 'start' DN, whatever extra attributes are selected.

Note that most of the methods in 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

    • DirectoryScan

      public DirectoryScan(DirectorySession ds, DN start, int depth)
      Initialise the DirectoryScan 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.
    • DirectoryScan

      public DirectoryScan(DirectorySession ds, DN start, boolean include_start, int depth, boolean sort)
      Initialise the DirectoryScan 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?
    • DirectoryScan

      public DirectoryScan(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 DirectoryScan 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

    • setCommonArgs

      public void setCommonArgs(CommonArgs args)
      Set the CommonArgs to use as a basis for the scan. By default the session-default CommonArgs are used as a basis, and are set up by the constructor. Note that a modified copy of the given CommonArgs is used, modified to make sure the alias settings are correct. This may be called from the GUI thread.
    • addSelection

      public void addSelection(AttributeType type)
      Add another attribute type to the list of attributes that should be fetched and returned during the scan. This may be called from the GUI thread.
      Parameters:
      type - AttributeType to add
    • setPageSizes

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

      public void addSelection(String type) throws BadAttributeTypeException
      Add another attribute type to the list of attributes that should be fetched and returned during the scan. This may be called from the GUI thread.
      Parameters:
      type - String name of AttributeType to add
      Throws:
      BadAttributeTypeException
    • hasNext

      public boolean hasNext()
      Check to see if there are any more entries 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<Entry>
      Returns:
      true if there are more entries to be returned
    • next

      public Entry next() throws NoSuchElementException
      Return the next Entry from the directory search. Entries 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<Entry>
      Returns:
      Entry instance
      Throws:
      NoSuchElementException - if the call is attempted after the last object has been returned.
    • remove

      public void remove() throws UnsupportedOperationException
      Remove operations are unsupported and generate an exception.
      Specified by:
      remove in interface Iterator<Entry>
      Throws:
      UnsupportedOperationException
    • 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 the GUI thread.

      Specified by:
      getException in interface DirectoryIterator<Entry>
    • getSearchCount

      public int getSearchCount()
      Return the number of searches performed so far. This counts all the pages of a paged-results search as one search only. This can be used by testing code to verify that the scan is working as designed.