Class DirectoryScan
- All Implemented Interfaces:
DirectoryIterator<Entry>
,Iterator<Entry>
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
-
Nested Class Summary
Nested classes/interfaces inherited from interface com.isode.dsapi.bulk.DirectoryIterator
DirectoryIterator.FatalException, DirectoryIterator.ScanException
-
Constructor Summary
ConstructorsConstructorDescriptionDirectoryScan
(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.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.DirectoryScan
(DirectorySession ds, DN start, int depth) Initialise the DirectoryScan to use the given directory session, start point, and depth of search. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addSelection
(AttributeType type) Add another attribute type to the list of attributes that should be fetched and returned during the scan.void
addSelection
(String type) Add another attribute type to the list of attributes that should be fetched and returned during the scan.Returns the next outstanding exception, or null if there are no more exceptions outstanding at this point in the scan.int
Return the number of searches performed so far.boolean
hasNext()
Check to see if there are any more entries to be returned from this directory scan.next()
Return the next Entry from the directory search.void
remove()
Remove operations are unsupported and generate an exception.void
setCommonArgs
(CommonArgs args) Set the CommonArgs to use as a basis for the scan.void
setPageSizes
(int dn_page_size) Override the default page-size of 1000 for DN searchesMethods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.util.Iterator
forEachRemaining
-
Constructor Details
-
DirectoryScan
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 usestart
- DN to start atdepth
- Depth to go below start DN (0 to return start DN only), or -1 for unlimited.
-
DirectoryScan
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 usestart
- DN to start atinclude_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 usestart
- DN to start atinclude_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 filteringfilter_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 nullchop_after
- List of chop-after DNs, or null
-
-
Method Details
-
setCommonArgs
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
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
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.
-
next
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 interfaceIterator<Entry>
- Returns:
- Entry instance
- Throws:
NoSuchElementException
- if the call is attempted after the last object has been returned.
-
remove
Remove operations are unsupported and generate an exception.- Specified by:
remove
in interfaceIterator<Entry>
- Throws:
UnsupportedOperationException
-
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 interfaceDirectoryIterator<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.
-