Previous | Next | Trail Map | Tips for LDAP Users | Searches

Batch Size

When you invoke list()(in the API reference documentation) , listBindings()(in the API reference documentation) , or any of the search()(in the API reference documentation) methods, the LDAP service provider interacts with the LDAP server to retrieve the results and return them in the form of a NamingEnumeration(in the API reference documentation) . 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()(in the API reference documentation) or NamingEnumeration.nextElement(). You can control how the LDAP service provider behaves in this respect by using the Context.BATCHSIZE(in the API reference documentation) (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 allows the program to unblock sooner. However, there is some overhead associated with processing each batch. Therefore, 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 need to be considered when choosing a batch size.

Here is 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()(in the API reference documentation)

Searches: End of Lesson

What's next? Now you can:


Previous | Next | Trail Map | Tips for LDAP Users | Searches