Directory servers organize entries somewhat like a file system. Directory data is often depicted as an upside-down tree.
In the figure shown above, entries are represented by the relevant
parts of their DNs. The entry with DN dc=example,dc=com
is the base entry for a suffix. Under the base entry, you see two
organizational units, one for people, ou=People
, the other
for groups, ou=Groups
. The entries for people include
those of Babs Jensen, Kirsten Vaughan, and Sam Carter.
When you are searching for a person's entry somewhere under
dc=example,dc=com
, you can start from
dc=example,dc=com
, from
ou=People,dc=example,dc=com
, or if you have enough
information to pinpoint the user entry and only want to look up another
attribute value for example, then directly from the entry such as
cn=Babs Jensen,ou=People,dc=example,dc=com
. The DN of
the entry where you choose to start the search is the base DN for the
search.
When searching, you also define the scope. Scope defines what entries the server considers when checking for entries that match your search.
-
For
SearchScope.BASE_OBJECT
the server considers only the base entry.This is the scope you use if you know the full DN of the object that interests you. For example, if your base DN points to Babs Jensen's entry,
cn=Babs Jensen,ou=People,dc=example,dc=com
, and you want to read some of Babs's attributes, you would set scope toSearchScope.BASE_OBJECT
. -
For
SearchScope.SINGLE_LEVEL
the server considers all entries directly below the base entry.You use this scope if for example you want to discover organizational units under
dc=example,dc=com
, or if you want to find people's entries and you know they are immediately underou=People,dc=example,dc=com
. -
For
SearchScope.SUBORDINATES
the server considers all entries below the base entry.This scope can be useful if you know that the base DN for your search is an entry that you do not want to match.
-
For
SearchScope.WHOLE_SUBTREE
(default) the server considers the base entry and all entries below.
In addition to a base DN and scope, a search request also calls for a search filter.