Package com.isode.dsapi.bulk

Class DirectoryDump

java.lang.Object
com.isode.dsapi.bulk.DirectoryDump
All Implemented Interfaces:
DirectoryIterator<ArrayList<Entry>>, Iterator<ArrayList<Entry>>
public class DirectoryDump extends Object implements DirectoryIterator<ArrayList<Entry>>
Iterate through all entries meeting the given conditions within a directory subtree. Entries are dumped in batches in whatever order they are received from the directory. Where possible, paged results are used. No special care is used to avoid limit errors. It is assumed that this will be used on directories that support paged results or else that are capable of returning large search results.

The search is structured as a series of one-level searches. However any one of those searches may short-circuit to a faster subtree search if all these conditions are met:

  • If there is no search filter or if the search filter applies only to children (i.e. 'filter_parents == false', aka deselect "Also apply filter to parent entries"), and ...
  • If there is no depth limit, and ...
  • If there are no chop-points which apply below the subtree search DN.

So the most extreme example would be if there is no search filter (or the search filter only applies to children), and there is no depth limit nor chop points, then the entire search reduces to a single subtree search.

Any exceptions generated during the scan due to exceeding size or time limits or due to other directory errors are queued, and may be requested by the caller at the end of the scan, or during the scan itself.

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. So this forces a series of one-level searches, which is slower.

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

    • DirectoryDump

      public DirectoryDump(DirectorySession ds, DN start, int depth, String filter, boolean filter_parents, List<DN> chop_before, List<DN> chop_after, Selection selection)
      Initialise the DirectoryDump 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
      depth - Depth to go below start DN (0 to return nothing, 1 to return only children of start DN, etc), or -1 for unlimited.
      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. 'false' is preferred because it gives more opportunity to switch to an LDAP subtree search, which is more efficient.
      chop_before - List of chop-before DNs, or null
      chop_after - List of chop-after DNs, or null
      selection - Which attributes to fetch

  • 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.

    • setPageSizes

      public void setPageSizes(int dn_page_size, int entry_page_size)
      Override the default page-sizes of 1000 for DN searches and 100 for entry searches

    • 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<ArrayList<Entry>>
      Returns:
      true if there are more entries to be returned

    • next

      public ArrayList<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<ArrayList<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<ArrayList<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<ArrayList<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.