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 to
SearchScope.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 under
ou=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.