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 number. The LDAP service provider uses the value of this property to determine how many results to read from the server before unblocking--this is called the batch size--and allowing the client program to get the results 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 0, the service provider will block until all results have been read. If this property has not been set, the default batch size is 1.

When you invoke search(), for example, 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 allow the program to unblock sooner. However, there is some overhead associated with processing each batch. If you are expecting a large number of results, 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 that much 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 initial context
DirContext ctx = new InitialDirContext(env);

// Perform 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 nor 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, which 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. See the Controls and Extensions lesson for details on how to use request controls with an LDAP "search" operation.

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