Searches

Batch Size

When you invoke list(), listBindings(), or any of the search() methods, the LDAP service provider interacts with the LDAP server to retrieve the results and returns them in the form of a NamingEnumeration. The LDAP service provider can collect all the results before returning the NamingEnumeration, or it can return each result as the caller invokes NamingEnumeration.next() or NamingEnumeration.nextElement(). You can control how the LDAP service provider behaves in this respect by using the Context.BATCHSIZE ("java.naming.batchsize") environment property. This property contains the string representation of a decimal integer. The LDAP service provider uses its value to determine how many results to read from the server before unblocking--this number of results is called the batch size--and allowing the client program to get the results by using next() or nextElement(). When the client program exhausts the batch, the LDAP service provider fetches another batch so that the client program can continue with the enumeration. If the batch size is zero, then the service provider will block until all results have been read. If this property was not set, then the default batch size is 1.

When you invoke search(), for example by using a batch size of n, the LDAP provider will block until it reads n results from the server before returning. So, setting the batch size to a smaller number allows the program to unblock sooner. However, some overhead attaches to processing each batch. If you are expecting a large number of results, then you might want to use a larger batch size to lower the number of context switches between the provider and your code. On the other hand, having a large batch also means that you need more memory to hold the results. These are the trade-offs that you'll need to consider when choosing a batch size.

Here's an example that sets the batch size to 10.

// Set the batch size to 10
env.put("java.naming.batchsize", "10");

// Create the initial context
DirContext ctx = new InitialDirContext(env);

// Perform the list
NamingEnumeration answer = ctx.list("ou=People"); 

Relationship to SearchControls.setCountLimit()

Note that the Context.BATCHSIZE environment property does not in any way affect how many results are returned or the order in which they are returned. It is completely unrelated to SearchControls.setCountLimit().

Batches at the Protocol Level

Context.BATCHSIZE controls the batch size only at the programmatic level. At the protocol level, an LDAP "search" operation causes the LDAP server to send all of the results to the client immediately. The LDAP provider stores all of the results that it receives--this might cause memory overflow problems.

LDAP servers that support either the Virtual List View or Paged Results control can be made to send results in batches at the protocol level. See the Controls and Extensions lesson for details on how to use request controls with LDAP "search" operations.

Searches: End of Lesson

What's next? Now you can:

• Continue on to the next lesson in this trail for tips on handling referrals.
• Go to the Schema lesson for tips on accessing the schema.
• Go to the Frequently Asked Questions lesson to read about questions that LDAP users have when using the JNDI.

Searches