Search Operation

The primary operation of LDAP servers. Provides the ability to retrieve multiple entries containing variable attribute sets using a defined query syntax. The syntax for LDAP filters is defined in RFC 2254.

Searches for entries matching: (&(givenName=daniel)(sn=fisher)) over the dc=ldaptive,dc=org DIT and returns entries containing just the mail and displayName attributes.

Connection conn = DefaultConnectionFactory.getConnection("ldap://directory.ldaptive.org");
try {
  conn.open();
  SearchOperation search = new SearchOperation(conn);
  SearchResult result = search.execute(
    new SearchRequest(
      "dc=ldaptive,dc=org","(&(givenName=daniel)(sn=fisher))", "mail", "displayName")).getResult();
  result.getEntry(); // if you're expecting a single entry
  for (LdapEntry entry : result.getEntries()) { // if you're expecting multiple entries
    // do something useful with the entry
  }

} finally {
  conn.close();
}

SearchRequest Properties

The following properties can be configured on a per request basis:

Name Default Value Description
baseDn ”” DN to search; An empty value searches the rootDSE;
searchFilter null LDAP filter to execute
returnAttributes null names of attributes to include in the search result
searchScope SUBTREE scope of the search; Valid values include: OBJECT, ONELEVEL, SUBTREE
timeLimit 0 length of time in milliseconds that a search operation should execute; A value of 0 means execute indefinitely; When time limit arrives result will contain any result returned up to that point
sizeLimit 0 maximum number of entries to include in the search result; A value of 0 means includes all entries
derefAliases null how aliases are dereferences; Valid values include: NEVER, SEARCHING, FINDING, ALWAYS; A null value means use the provider default
typesOnly false whether to return attribute types only
binaryAttributes null attribute names that should be considered binary regardless of how they are stored
sortBehavior UNORDERED how result data should be sorted; Valid values include: UNORDERED, ORDERED, SORTED
searchEntryHandlers null entry handlers to process each entry in the result
searchReferenceHandlers null reference handlers to process each reference in the result

Search Filters

The SearchFilter object provides support for both positional and named parameters. Values provided as parameters are escaped according to RFC 2254.

Positional

SearchFilter filter = new SearchFilter("(|(uid={0})(mail={1}))");
filter.setParameters(new Object[] {"1234", "dfisher*@ldaptive.org"});

Named

SearchFilter filter = new SearchFilter("(|(uid={uid})(mail={mail}))");
filter.setParameter("uid", "1234");
filter.setParameter("mail", "dfisher*@ldaptive.org");

In this manner applications can define custom, readable filters for their users and then set the parameters accordingly.

Search Result Order

The result data stored in the SearchResult, LdapEntry, and LdapAttribute objects is unordered by default. The following implementations are provided:

The sort behavior can be controlled on a per request basis with:

searchRequest.setSortBehavior(SortBehavior.SORTED);

The default sort behavior can be controlled with a JVM switch:

-Dorg.ldaptive.sortBehavior=org.ldaptive.SortBehavior.ORDERED

Search Result Caching

The search operation supports supplying a cache when executing a request. The interface for Cache looks like:

public interface Cache<Q extends SearchRequest>
{
  SearchResult get(Q request);
  void put(Q request, SearchResult result);
}

If a cache is supplied, it will be inspected for each request and will forgo sending the request to the LDAP if a cached result is found. Ldaptive provides one implementation called LRUCache which leverages a LinkedHashMap to store requests and responses. To use a cache invoke the search operation like this:

// create a cache with size=50, timeToLive=10min, interval=5min
LRUCache<SearchRequest> cache = new LRUCache<SearchRequest>(50, Duration.ofMinutes(10), Duration.ofMinutes(5));
Connection conn = DefaultConnectionFactory.getConnection("ldap://directory.ldaptive.org");
try {
  conn.open();
  SearchOperation search = new SearchOperation(conn, cache);
  SearchResult result = search.execute(new SearchRequest("dc=ldaptive,dc=org", "(uid=dfisher)")).getResult();
} finally {
  conn.close();
}